diff --git a/docs/azure/includes/dotnet-all.md b/docs/azure/includes/dotnet-all.md index 492ae17b18798..9e5f6a78ffee8 100644 --- a/docs/azure/includes/dotnet-all.md +++ b/docs/azure/includes/dotnet-all.md @@ -88,7 +88,7 @@ | Provisioning - Resources | NuGet [0.2.0](https://www.nuget.org/packages/Azure.Provisioning.Resources/0.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.Resources-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Resources_0.2.0/sdk/provisioning/Azure.Provisioning.Resources/) | | Purview Account | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Analytics.Purview.Account/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Analytics.Purview.Account-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.Account_1.0.0-beta.1/sdk/purview/Azure.Analytics.Purview.Account/) | | Purview Administration | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Analytics.Purview.Administration/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Analytics.Purview.Administration-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.Administration_1.0.0-beta.1/sdk/purview/Azure.Analytics.Purview.Administration/) | -| Purview Data Map | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Analytics.Purview.DataMap/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Analytics.Purview.DataMap-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.DataMap_1.0.0-beta.1/sdk/purview/Azure.Analytics.Purview.DataMap/) | +| Purview Data Map | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Analytics.Purview.DataMap/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Analytics.Purview.DataMap-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.DataMap_1.0.0-beta.2/sdk/purview/Azure.Analytics.Purview.DataMap/) | | Purview Scanning | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Analytics.Purview.Scanning/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Analytics.Purview.Scanning-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.Scanning_1.0.0-beta.2/sdk/purview/Azure.Analytics.Purview.Scanning/) | | Purview Sharing | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Analytics.Purview.Sharing/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Analytics.Purview.Sharing-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.Sharing_1.0.0-beta.3/sdk/purview/Azure.Analytics.Purview.Sharing/) | | Purview Workflow | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Analytics.Purview.Workflows/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Analytics.Purview.Workflows-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.Workflows_1.0.0-beta.2/sdk/purview/Azure.Analytics.Purview.Workflows/) | diff --git a/docs/azure/includes/dotnet-new.md b/docs/azure/includes/dotnet-new.md index 6f407cb41a77d..2a41dc1739d10 100644 --- a/docs/azure/includes/dotnet-new.md +++ b/docs/azure/includes/dotnet-new.md @@ -91,7 +91,7 @@ | Purview Account | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Analytics.Purview.Account/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Analytics.Purview.Account-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.Account_1.0.0-beta.1/sdk/purview/Azure.Analytics.Purview.Account/) | | Purview Administration | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Analytics.Purview.Administration/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Analytics.Purview.Administration-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.Administration_1.0.0-beta.1/sdk/purview/Azure.Analytics.Purview.Administration/) | | Purview Catalog | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.Analytics.Purview.Catalog/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Analytics.Purview.Catalog-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.Catalog_1.0.0-beta.4/sdk/purview/Azure.Analytics.Purview.Catalog/) | -| Purview Data Map | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Analytics.Purview.DataMap/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Analytics.Purview.DataMap-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.DataMap_1.0.0-beta.1/sdk/purview/Azure.Analytics.Purview.DataMap/) | +| Purview Data Map | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Analytics.Purview.DataMap/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Analytics.Purview.DataMap-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.DataMap_1.0.0-beta.2/sdk/purview/Azure.Analytics.Purview.DataMap/) | | Purview Scanning | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Analytics.Purview.Scanning/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Analytics.Purview.Scanning-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.Scanning_1.0.0-beta.2/sdk/purview/Azure.Analytics.Purview.Scanning/) | | Purview Share | NuGet [1.0.3-beta.20](https://www.nuget.org/packages/Azure.Analytics.Purview.Share/1.0.3-beta.20) | [docs](/dotnet/api/overview/azure/Analytics.Purview.Share-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.3-beta.20](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.Share_1.0.3-beta.20/sdk/purview/Azure.Analytics.Purview.Share) | | Purview Sharing | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Analytics.Purview.Sharing/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Analytics.Purview.Sharing-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.Sharing_1.0.0-beta.3/sdk/purview/Azure.Analytics.Purview.Sharing/) | diff --git a/docs/core/extensions/globalization.md b/docs/core/extensions/globalization.md index f426ab0b256a8..2375f31553502 100644 --- a/docs/core/extensions/globalization.md +++ b/docs/core/extensions/globalization.md @@ -128,15 +128,11 @@ How you handle date and time values depends on whether they are displayed in the Typically, when dates and times are displayed in the user interface, you should use the formatting conventions of the user's culture, which is defined by the property and by the object returned by the `CultureInfo.CurrentCulture.DateTimeFormat` property. The formatting conventions of the current culture are automatically used when you format a date by using any of these methods: -- The parameterless method - -- The method, which includes a format string - -- The parameterless method - -- The , which includes a format string - -- The [composite formatting](../../standard/base-types/composite-formatting.md) feature, when it is used with dates +- The parameterless method. +- The method, which includes a format string. +- The parameterless method. +- The , which includes a format string. +- The [composite formatting](../../standard/base-types/composite-formatting.md) feature, when it is used with dates. The following example displays sunrise and sunset data twice for October 11, 2012. It first sets the current culture to Croatian (Croatia), and then to English (United Kingdom). In each case, the dates and times are displayed in the format that is appropriate for that culture. diff --git a/docs/core/testing/microsoft-testing-platform-extensions-policy.md b/docs/core/testing/microsoft-testing-platform-extensions-policy.md index 2f2e39e7d7fd7..8399ba024c622 100644 --- a/docs/core/testing/microsoft-testing-platform-extensions-policy.md +++ b/docs/core/testing/microsoft-testing-platform-extensions-policy.md @@ -24,8 +24,8 @@ This extension is shipped as part of [Microsoft.Testing.Extensions.Retry](https: The available options are as follows: -| Option | Description | -|-----------------------------------|--------------------------------------------------------------------------------------------------| -| retry-failed-tests | Reruns any failed tests until they pass or until the maximum number of attempts is reached. | -| retry-failed-tests-max-percentage | Avoids rerunning tests when the percentage of failed test cases crosses the specified threshold. | -| retry-failed-tests-max-tests | Avoids rerunning tests when the number of failed test cases crosses the specified limit. | +| Option | Description | +|---------------------------------------|--------------------------------------------------------------------------------------------------| +| `--retry-failed-tests` | Reruns any failed tests until they pass or until the maximum number of attempts is reached. | +| `--retry-failed-tests-max-percentage` | Avoids rerunning tests when the percentage of failed test cases crosses the specified threshold. | +| `--retry-failed-tests-max-tests` | Avoids rerunning tests when the number of failed test cases crosses the specified limit. | diff --git a/docs/core/testing/microsoft-testing-platform-integration-dotnet-test.md b/docs/core/testing/microsoft-testing-platform-integration-dotnet-test.md index 37e690a993f9a..75cb30d95fe02 100644 --- a/docs/core/testing/microsoft-testing-platform-integration-dotnet-test.md +++ b/docs/core/testing/microsoft-testing-platform-integration-dotnet-test.md @@ -1,26 +1,29 @@ --- -title: Use Microsoft.Testing.Platform with VSTest mode of `dotnet test` +title: Use Microsoft.Testing.Platform in the VSTest mode of `dotnet test` description: Learn how to run Microsoft.Testing.Platform tests through dotnet test. author: nohwnd ms.author: jajares ms.date: 03/26/2025 --- -# Use Microsoft.Testing.Platform with VSTest mode of `dotnet test` +# Use Microsoft.Testing.Platform in the VSTest mode of `dotnet test` -This article describes `dotnet test` integration for Microsoft.Testing.Platform that is provided by Microsoft.Testing.Platform.MSBuild when running with VSTest mode of `dotnet test`. +This article explains the integration of `dotnet test` for Microsoft.Testing.Platform, which is provided by Microsoft.Testing.Platform.MSBuild when running in the VSTest mode of `dotnet test`. -Before reading this article, it's advised to read [Testing with dotnet test](unit-testing-with-dotnet-test.md) first. +Before diving into this article, it's recommended to first read [Testing with dotnet test](unit-testing-with-dotnet-test.md), which explains the two modes of `dotnet test` (VSTest and MTP modes). -By default, `dotnet test` is using VSTest behavior to run tests. To enable support for `Microsoft.Testing.Platform` in `dotnet test`, there are two options: +By default, `dotnet test` uses VSTest to run tests. To enable support for `Microsoft.Testing.Platform` in `dotnet test`, you have two options: -1. Use `dotnet test` in VSTest mode, and specify `true` MSBuild property in your project file. -2. Use `dotnet test` in MTP mode, and enjoy more native support of MTP in `dotnet test`. This is only supported starting with .NET 10 SDK. +1. Use `dotnet test` in VSTest mode and specify `true` MSBuild property in your project file. +2. Use `dotnet test` in MTP mode for more native support of MTP in `dotnet test`, which is only supported starting with the .NET 10 SDK. -Both of these options are explained in details in the [Testing with dotnet test](unit-testing-with-dotnet-test.md) article. +Both options are explained in detail in the [Testing with dotnet test](unit-testing-with-dotnet-test.md) article. > [!IMPORTANT] -> The remaining of this article is specific to the first option. +> The rest of this article is specific to the VSTest mode of `dotnet test`. +> +> [!CAUTION] +> Starting with .NET 10 SDK, it's recommended to not use the VSTest mode of `dotnet test` when running with Microsoft.Testing.Platform. ## Show failure per test diff --git a/docs/core/testing/unit-testing-mstest-sdk.md b/docs/core/testing/unit-testing-mstest-sdk.md index fae458543daa1..fc27fba9e0064 100644 --- a/docs/core/testing/unit-testing-mstest-sdk.md +++ b/docs/core/testing/unit-testing-mstest-sdk.md @@ -61,7 +61,7 @@ You don't need anything else to build and run your tests and you can use the sam > [!IMPORTANT] > By switching to the `MSTest.Sdk`, you opt in to using the [MSTest runner (enables Microsoft.Testing.Platform for MSTest)](./unit-testing-mstest-runner-intro.md), including with [dotnet test](./microsoft-testing-platform-integration-dotnet-test.md). That requires modifying your CI and local CLI calls, and also impacts the available entries of the _.runsettings_. You can use `MSTest.Sdk` and still keep the old integrations and tools by instead switching the [runner](#select-the-runner). -> In more details, MSTest.Sdk, by default, will set `EnableMSTestRunner` and `TestingPlatformDotnetTestSupport` to true. For more information about dotnet test and its different modes for running Microsoft.Testing.Platform, see [Testing with dotnet test](./unit-testing-with-dotnet-test.md). +> By default, MSTest.Sdk sets `EnableMSTestRunner` and `TestingPlatformDotnetTestSupport` to true. For more information about dotnet test and its different modes for running Microsoft.Testing.Platform, see [Testing with dotnet test](./unit-testing-with-dotnet-test.md). ## Select the runner diff --git a/docs/core/testing/unit-testing-with-dotnet-test.md b/docs/core/testing/unit-testing-with-dotnet-test.md index 7335dfc070b2c..64505d8d07fcf 100644 --- a/docs/core/testing/unit-testing-with-dotnet-test.md +++ b/docs/core/testing/unit-testing-with-dotnet-test.md @@ -26,18 +26,16 @@ The process involves invoking the `VSTest` MSBuild target, which triggers other ### Run MTP projects with VSTest mode -`dotnet test` is typically designed to run VSTest projects in VSTest mode, as that was its original purpose. However, to run MTP projects in `dotnet test` VSTest mode, you can use the [Microsoft.Testing.Platform.MSBuild](https://www.nuget.org/packages/Microsoft.Testing.Platform.MSBuild). From the user's perspective, this support is enabled by setting the `TestingPlatformDotnetTestSupport` MSBuild property to true (it is false by default for backward compatibility reasons). In simple terms, setting this property to true will cause Microsoft.Testing.Platform.MSBuild to change the `VSTest` target behavior, redirecting it to call `InvokeTestingPlatform`. This is an MSBuild target included in Microsoft.Testing.Platform.MSBuild, responsible for correctly running MTP test applications as executables. This means that VSTest-specific command-line options are silently ignored in this mode, such as `--logger`. This implies that there should be a way to pass MTP-specific command-line options, such as `--report-trx`, which is equivalent to using `--logger trx` in VSTest. Given the current limitations of the `dotnet test` CLI, the only way to include MTP-specific arguments is by appending them after an additional `--`. For instance, `dotnet test -- --report-trx`. +`dotnet test` was designed to run VSTest projects in VSTest mode. However, you can run MTP projects in `dotnet test` VSTest mode by using the [Microsoft.Testing.Platform.MSBuild](https://www.nuget.org/packages/Microsoft.Testing.Platform.MSBuild) package. From the user's perspective, this support is enabled by setting the `TestingPlatformDotnetTestSupport` MSBuild property to `true` (it's `false` by default for backward-compatibility reasons). When this property is set to `true`, Microsoft.Testing.Platform.MSBuild changes the `VSTest` target behavior, redirecting it to call `InvokeTestingPlatform`. `InvokeTestingPlatform` is an MSBuild target included in Microsoft.Testing.Platform.MSBuild that's responsible for correctly running MTP test applications as executables. VSTest-specific command-line options, such as `--logger`, are silently ignored in this mode. To include MTP-specific arguments, such as `--report-trx`, you must append them after an additional `--`. For example, `dotnet test -- --report-trx`. > [!NOTE] -> MSTest and NUnit use [Microsoft.Testing.Extensions.VSTestBridge](https://www.nuget.org/packages/Microsoft.Testing.Extensions.VSTestBridge). When you set `EnableMSTestRunner` or `EnableNUnitRunner` (the properties used to enable MTP), your test project become supporting both VSTest and Microsoft.Testing.Platform. -> In that case, if you are using VSTest mode of `dotnet test` and not setting `TestingPlatformDotnetTestSupport` to true, you are actually running completely with VSTest, as if `EnableMSTestRunner` and `EnableNUnitRunner` are not there. +> MSTest and NUnit use the [Microsoft.Testing.Extensions.VSTestBridge](https://www.nuget.org/packages/Microsoft.Testing.Extensions.VSTestBridge) package. By setting `EnableMSTestRunner` or `EnableNUnitRunner` (which enables Microsoft.Testing.Platform), your test project will support both VSTest and Microsoft.Testing.Platform. +> In that scenario, if you use the VSTest mode of `dotnet test` and do not set `TestingPlatformDotnetTestSupport` to true, you are essentially running entirely with VSTest, as if `EnableMSTestRunner` and `EnableNUnitRunner` are not set to true. > > [!NOTE] -> It's highly recommended that you set the `TestingPlatformDotnetTestSupport` property in `Directory.Build.props`. That way, you don't have to add it to every test project file, and you don't risk introducing a new project that doesn't set this property and end up with a solution where some projects are VSTest while others are Microsoft.Testing.Platform, which may not work correctly and is unsupported scenario. +> It is highly recommended to set the `TestingPlatformDotnetTestSupport` property in `Directory.Build.props`. This ensures that you don't need to add it to every test project file individually. Additionally, it prevents the risk of introducing a new test project that doesn't set this property, which could result in a solution where some projects use VSTest while others use Microsoft.Testing.Platform. This mixed configuration might not work correctly and is an unsupported scenario. -The following command-line options of `dotnet test` command in VSTest mode are supported by Microsoft.Testing.Platform. These options are build-specific and not passed down to VSTest, which is why they work well with MTP. - -The list below described all `dotnet test` command line options that are supported by `Microsoft.Testing.Platform`: +The following list outlines the command-line options of `dotnet test` command in VSTest mode that are supported by Microsoft.Testing.Platform. These options are specific to the build process and not passed down to VSTest, which is why they work with MTP. - `-a|--arch ` - `--artifacts-path ` diff --git a/docs/core/tutorials/cli-templates-create-template-package.md b/docs/core/tutorials/cli-templates-create-template-package.md index 9b0fe9fbdc373..cc695663f8aa1 100644 --- a/docs/core/tutorials/cli-templates-create-template-package.md +++ b/docs/core/tutorials/cli-templates-create-template-package.md @@ -127,7 +127,7 @@ These MSBuild tasks provide template validation and [localization of the templat ## Pack and install -Save the project file. Before building the template package, verify that your folder structure is correct. Any template you want to pack should be placed in the _templates_ folder, in its own folder. The folder structure should look similar to the following hierarchy: +Save the project file. Before building the template package, verify that your folder structure is correct. Any template you want to pack should be placed in the _content_ folder, in its own folder. The folder structure should look similar to the following hierarchy: ```console working diff --git a/docs/csharp/language-reference/tokens/interpolated.md b/docs/csharp/language-reference/tokens/interpolated.md index e89d08f401e94..fab7606294997 100644 --- a/docs/csharp/language-reference/tokens/interpolated.md +++ b/docs/csharp/language-reference/tokens/interpolated.md @@ -29,16 +29,16 @@ To identify a string literal as an interpolated string, prepend it with the `$` The structure of an item with an interpolation expression is as follows: ```csharp -{[,][:]} +{[,][:]} ``` Elements in square brackets are optional. The following table describes each element: -| Element | Description | -|--|--| +| Element | Description | +|---------------------------|-------------| | `interpolationExpression` | The expression that produces a result to be formatted. When the expression is `null`, the output is the empty string (). | -| `alignment` | The constant expression whose value defines the minimum number of characters in the string representation of the expression result. If positive, the string representation is right-aligned; if negative, left-aligned. For more information, see the [Alignment component](../../../standard/base-types/composite-formatting.md#alignment-component) section of the [Composite formatting](../../../standard/base-types/composite-formatting.md) article. | -| `formatString` | A format string supported by the type of the expression result. For more information, see the [Format string component](../../../standard/base-types/composite-formatting.md#format-string-component) section of the [Composite formatting](../../../standard/base-types/composite-formatting.md) article. | +| `width` | The constant expression whose value defines the minimum number of characters in the string representation of the expression result. If positive, the string representation is right-aligned; if negative, left-aligned. For more information, see the [Width component](../../../standard/base-types/composite-formatting.md#width-component) section of the [Composite formatting](../../../standard/base-types/composite-formatting.md) article. | +| `formatString` | A format string supported by the type of the expression result. For more information, see the [Format string component](../../../standard/base-types/composite-formatting.md#format-string-component) section of the [Composite formatting](../../../standard/base-types/composite-formatting.md) article. | The following example uses optional formatting components described in the preceding table: @@ -95,7 +95,7 @@ If you're new to string interpolation, see the [String interpolation in C#](../. The compiler checks if an interpolated string is assigned to a type that satisfies the [_interpolated string handler pattern_](~/_csharplang/proposals/csharp-10.0/improved-interpolated-strings.md#the-handler-pattern). An _interpolated string handler_ is a type that converts the interpolated string into a result string. When an interpolated string has the type `string`, it's processed by the . For the example of a custom interpolated string handler, see the [Write a custom string interpolation handler](../../advanced-topics/performance/interpolated-string-handler.md) tutorial. Use of an interpolated string handler is an advanced scenario, typically required for performance reasons. > [!NOTE] -> One side effect of interpolated string handlers is that a custom handler, including , may not evaluate all the interpolation expressions within the interpolated string under all conditions. That means side effects of those expressions may not occur. +> One side effect of interpolated string handlers is that a custom handler, including , might not evaluate all the interpolation expressions within the interpolated string under all conditions. That means side effects of those expressions might not occur. If an interpolated string has the type `string`, it's typically transformed into a method call. The compiler can replace with if the analyzed behavior would be equivalent to concatenation. diff --git a/docs/csharp/programming-guide/strings/index.md b/docs/csharp/programming-guide/strings/index.md index 44145108a3f0c..35f77255e8721 100644 --- a/docs/csharp/programming-guide/strings/index.md +++ b/docs/csharp/programming-guide/strings/index.md @@ -108,7 +108,7 @@ A format string is a string whose contents are determined dynamically at run tim You declare [*Interpolated strings*](../../language-reference/tokens/interpolated.md) with the `$` special character. An interpolated string includes interpolated expressions in braces. If you're new to string interpolation, see the [String interpolation - C# interactive tutorial](../../tutorials/exploration/interpolated-strings.yml) for a quick overview. -Use string interpolation to improve the readability and maintainability of your code. String interpolation achieves the same results as the `String.Format` method, but improves ease of use and inline clarity. +Use string interpolation to improve the readability and maintainability of your code. String interpolation achieves the same results as the `String.Format` method, but is easier to use and improves inline clarity. :::code language="csharp" source="./snippets/StringInterpolation.cs" id="StringInterpolation"::: @@ -132,7 +132,7 @@ The utilizes placeho :::code language="csharp" source="./snippets/StringInterpolation.cs" id="StringFormat"::: -For more information on formatting .NET types, see [Formatting Types in .NET](../../../standard/base-types/formatting-types.md). +For more information, see [Composite formatting in .NET](../../../standard/base-types/composite-formatting.md). ## Substrings diff --git a/docs/csharp/tutorials/string-interpolation.md b/docs/csharp/tutorials/string-interpolation.md index 3acdae650080e..5bf22fd22279f 100644 --- a/docs/csharp/tutorials/string-interpolation.md +++ b/docs/csharp/tutorials/string-interpolation.md @@ -25,7 +25,7 @@ Interpolated strings support all the capabilities of the [string composite forma ## How to specify a format string for an interpolation expression -To specify a format string that is supported by the type of the expression result, follow the interpolation expression with a colon (":") and the format string: +To specify a format string that's supported by the type of the expression result, follow the interpolation expression with a colon (":") and the format string: ```csharp {:} @@ -42,24 +42,24 @@ For more information, see the [Format string component](../../standard/base-type To specify the minimum field width and the alignment of the formatted expression result, follow the interpolation expression with a comma (",") and the constant expression: ```csharp -{,} +{,} ``` -If the *alignment* value is positive, the formatted expression result is right-aligned; if negative, it's left-aligned. +If the *width* value is positive, the formatted expression result is right-aligned; if negative, it's left-aligned. -If you need to specify both alignment and a format string, start with the alignment component: +If you need to specify both width and a format string, start with the width component: ```csharp -{,:} +{,:} ``` -The following example shows how to specify alignment and uses pipe characters ("|") to delimit text fields: +The following example shows how to specify width and alignment, and uses pipe characters ("|") to delimit text fields: :::code language="csharp" interactive="try-dotnet-method" source="./snippets/StringInterpolation/Program.cs" id="AlignmentAndFormatString"::: -As the example output shows, if the length of the formatted expression result exceeds specified field width, the *alignment* value is ignored. +As the example output shows, if the length of the formatted expression result exceeds specified field width, the *width* value is ignored. -For more information, see the [Alignment component](../../standard/base-types/composite-formatting.md#alignment-component) section of the [Composite formatting](../../standard/base-types/composite-formatting.md) article. +For more information, see the [Width component](../../standard/base-types/composite-formatting.md#width-component) section of the [Composite formatting](../../standard/base-types/composite-formatting.md) article. ## How to use escape sequences in an interpolated string diff --git a/docs/framework/configure-apps/file-schema/runtime/timespan-legacyformatmode-element.md b/docs/framework/configure-apps/file-schema/runtime/timespan-legacyformatmode-element.md index f5c116176f680..d220bb884168a 100644 --- a/docs/framework/configure-apps/file-schema/runtime/timespan-legacyformatmode-element.md +++ b/docs/framework/configure-apps/file-schema/runtime/timespan-legacyformatmode-element.md @@ -16,7 +16,7 @@ Determines whether the runtime preserves legacy behavior in formatting operation [**\**](../configuration-element.md)\   [**\**](runtime-element.md)\ -    **\** +    **\** ## Syntax @@ -37,10 +37,10 @@ The following sections describe attributes, child elements, and parent elements. ## enabled Attribute -|Value|Description| -|-----------|-----------------| -|`false`|The runtime does not restore legacy formatting behavior.| -|`true`|The runtime restores legacy formatting behavior.| +| Value | Description | +|---------|----------------------------------------------------------| +| `false` | The runtime does not restore legacy formatting behavior. | +| `true` | The runtime restores legacy formatting behavior. | ### Child Elements @@ -48,16 +48,16 @@ None. ### Parent Elements -|Element|Description| -|-------------|-----------------| -|`configuration`|The root element in every configuration file used by the common language runtime and .NET Framework applications.| -|`runtime`|Contains information about runtime initialization options.| +| Element | Description | +|-----------------|------------------------------------------------------------| +| `configuration` | The root element in every configuration file used by the common language runtime and .NET Framework applications. | +| `runtime` | Contains information about runtime initialization options. | ## Remarks -Starting with the .NET Framework 4, the structure implements the interface and supports formatting operations with standard and custom format strings. If a parsing method encounters an unsupported format specifier or format string, it throws a . +Starting with .NET Framework 4, the structure implements the interface and supports formatting operations with standard and custom format strings. If a parsing method encounters an unsupported format specifier or format string, it throws a . -In previous versions of the .NET Framework, the structure did not implement and did not support format strings. However, many developers mistakenly assumed that did support a set of format strings and used them in [composite formatting operations](../../../../standard/base-types/composite-formatting.md) with methods such as . Ordinarily, if a type implements and supports format strings, calls to formatting methods with unsupported format strings usually throw a . However, because did not implement , the runtime ignored the format string and instead called the method. This means that, although the format strings had no effect on the formatting operation, their presence did not result in a . +In previous versions of .NET Framework, the structure did not implement and did not support format strings. However, many developers mistakenly assumed that did support a set of format strings and used them in [composite formatting operations](../../../../standard/base-types/composite-formatting.md) with methods such as . Ordinarily, if a type implements and supports format strings, calls to formatting methods with unsupported format strings usually throw a . However, because did not implement , the runtime ignored the format string and instead called the method. This means that, although the format strings had no effect on the formatting operation, their presence did not result in a . For cases in which legacy code passes a composite formatting method and an invalid format string, and that code cannot be recompiled, you can use the `` element to restore the legacy behavior. When you set the `enabled` attribute of this element to `true`, the composite formatting method results in a call to rather than , and a is not thrown. @@ -68,7 +68,7 @@ The following example instantiates a object and attempts [!code-csharp[TimeSpan.BreakingChanges#1](../../../../../samples/snippets/csharp/VS_Snippets_CLR/timespan.breakingchanges/cs/legacyformatmode1.cs#1)] [!code-vb[TimeSpan.BreakingChanges#1](../../../../../samples/snippets/visualbasic/VS_Snippets_CLR/timespan.breakingchanges/vb/legacyformatmode1.vb#1)] -When you run the example on the .NET Framework 3.5 or on an earlier version, it displays the following output: +When you run the example on .NET Framework 3.5 or on an earlier version, it displays the following output: ```console 12:30:45 @@ -80,7 +80,7 @@ This differs markedly from the output if you run the example on the .NET Framewo Invalid Format ``` -However, if you add the following configuration file to the example's directory and then run the example on the .NET Framework 4 or later version, the output is identical to that produced by the example when it is run on .NET Framework 3.5. +However, if you add the following configuration file to the example's directory and then run the example on .NET Framework 4 or a later version, the output is identical to that produced by the example when it is run on .NET Framework 3.5. ```xml diff --git a/docs/fundamentals/runtime-libraries/includes/interpolated-strings.md b/docs/fundamentals/runtime-libraries/includes/interpolated-strings.md index f12aa8b3bebef..b5ec035942008 100644 --- a/docs/fundamentals/runtime-libraries/includes/interpolated-strings.md +++ b/docs/fundamentals/runtime-libraries/includes/interpolated-strings.md @@ -1,2 +1,2 @@ > [!IMPORTANT] -> Instead of calling the **String.Format** method or using [composite format strings](../../../standard/base-types/composite-formatting.md), you can use *interpolated strings* if your language supports them. An interpolated string is a string that contains *interpolated expressions*. Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. For more information, see [String interpolation (C# Reference)](../../../csharp/language-reference/tokens/interpolated.md) and [Interpolated Strings (Visual Basic Reference)](../../../visual-basic/programming-guide/language-features/strings/interpolated-strings.md). +> Instead of calling the **String.Format** method or using [composite format strings](../../../standard/base-types/composite-formatting.md), you can use *interpolated strings* if your language supports them. An interpolated string is a string that contains *interpolated expressions*. Each interpolated expression is resolved with the expression's value and included in the result string when the string is assigned. For more information, see [String interpolation (C# Reference)](../../../csharp/language-reference/tokens/interpolated.md) and [Interpolated strings (Visual Basic Reference)](../../../visual-basic/programming-guide/language-features/strings/interpolated-strings.md). diff --git a/docs/fundamentals/runtime-libraries/system-double.md b/docs/fundamentals/runtime-libraries/system-double.md index 5213cd68488fd..a925bb4e6e208 100644 --- a/docs/fundamentals/runtime-libraries/system-double.md +++ b/docs/fundamentals/runtime-libraries/system-double.md @@ -191,7 +191,7 @@ The structure and related types provide methods to perform - **Rounding**. Rounding is often used as a technique for reducing the impact of differences between values caused by problems of floating-point representation and precision. You can round a value by calling the method. -- **Formatting**. You can convert a value to its string representation by calling the method or by using the composite formatting feature. For information about how format strings control the string representation of floating-point values, see the [Standard Numeric Format Strings](../../standard/base-types/standard-numeric-format-strings.md) and [Custom Numeric Format Strings](../../standard/base-types/custom-numeric-format-strings.md) topics. +- **Formatting**. You can convert a value to its string representation by calling the method or by using the composite formatting feature. For information about how format strings control the string representation of floating-point values, see [Standard Numeric Format Strings](../../standard/base-types/standard-numeric-format-strings.md) and [Custom Numeric Format Strings](../../standard/base-types/custom-numeric-format-strings.md). - **Parsing strings**. You can convert the string representation of a floating-point value to a value by calling either the or method. If the parse operation fails, the method throws an exception, whereas the method returns `false`. diff --git a/docs/fundamentals/runtime-libraries/system-single.md b/docs/fundamentals/runtime-libraries/system-single.md index 8a97f9ab8fdb2..d755f8189e370 100644 --- a/docs/fundamentals/runtime-libraries/system-single.md +++ b/docs/fundamentals/runtime-libraries/system-single.md @@ -201,7 +201,7 @@ The structure and related types provide methods to perform - **Rounding**. Rounding is often used as a technique for reducing the impact of differences between values caused by problems of floating-point representation and precision. You can round a value by calling the method. However, note that the value is converted to a before the method is called, and the conversion can involve a loss of precision. -- **Formatting**. You can convert a value to its string representation by calling the method or by using the [composite formatting](../../standard/base-types/composite-formatting.md) feature. For information about how format strings control the string representation of floating-point values, see the [Standard Numeric Format Strings](../../standard/base-types/standard-numeric-format-strings.md) and [Custom Numeric Format Strings](../../standard/base-types/custom-numeric-format-strings.md) topics. +- **Formatting**. You can convert a value to its string representation by calling the method or by using the [composite formatting](../../standard/base-types/composite-formatting.md) feature. For information about how format strings control the string representation of floating-point values, see [Standard Numeric Format Strings](../../standard/base-types/standard-numeric-format-strings.md) and [Custom Numeric Format Strings](../../standard/base-types/custom-numeric-format-strings.md). - **Parsing strings**. You can convert the string representation of a floating-point value to a value by calling the or method. If the parse operation fails, the method throws an exception, whereas the method returns `false`. diff --git a/docs/fundamentals/runtime-libraries/system-string-format.md b/docs/fundamentals/runtime-libraries/system-string-format.md index be6167ae737be..9cfae849a28bb 100644 --- a/docs/fundamentals/runtime-libraries/system-string-format.md +++ b/docs/fundamentals/runtime-libraries/system-string-format.md @@ -85,11 +85,11 @@ You can follow the index in a format item with a format string to control how an :::code language="fsharp" source="./snippets/System/FormatException/Overview/fsharp/starting1.fs" id="Snippet32"::: :::code language="vb" source="./snippets/System/String/Format/vb/starting1.vb" id="Snippet32"::: -A number of types support format strings, including all numeric types (both [standard](../../standard/base-types/standard-numeric-format-strings.md) and [custom](../../standard/base-types/custom-numeric-format-strings.md) format strings), all dates and times (both [standard](../../standard/base-types/standard-date-and-time-format-strings.md) and [custom](../../standard/base-types/custom-date-and-time-format-strings.md) format strings) and time intervals (both [standard](../../standard/base-types/standard-timespan-format-strings.md) and [custom](../../standard/base-types/custom-timespan-format-strings.md) format strings), all enumeration types [enumeration types](../../standard/base-types/enumeration-format-strings.md), and [GUIDs](xref:System.Guid.ToString(System.String)). You can also add support for format strings to your own types. +Numerous types support format strings, including all numeric types (both [standard](../../standard/base-types/standard-numeric-format-strings.md) and [custom](../../standard/base-types/custom-numeric-format-strings.md) format strings), all dates and times (both [standard](../../standard/base-types/standard-date-and-time-format-strings.md) and [custom](../../standard/base-types/custom-date-and-time-format-strings.md) format strings) and time intervals (both [standard](../../standard/base-types/standard-timespan-format-strings.md) and [custom](../../standard/base-types/custom-timespan-format-strings.md) format strings), all enumeration types [enumeration types](../../standard/base-types/enumeration-format-strings.md), 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.) +You can define the width of the string that's 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. @@ -111,8 +111,8 @@ The following example is similar to the previous one, except that it left-aligns ## Which method do I call? -|To|Call| -|--------|----------| +| Objective | Method 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.| @@ -130,7 +130,7 @@ Each overload of the method uses the [composite f A format item has this syntax: ```txt -{index[,alignment][:formatString]} +{index[,width][: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](../../standard/base-types/composite-formatting.md#escaping-braces) section in the [Composite Formatting](../../standard/base-types/composite-formatting.md) article.) @@ -143,16 +143,16 @@ For example, a format item to format a currency value might appear like this: A format item has the following elements: -*index*\ +`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. +`width`\ +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 `width`, 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. +If the value of `width` is less than the length of the argument to be inserted, `width` 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: +`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](../../standard/base-types/standard-numeric-format-strings.md) and [Custom Numeric Format Strings](../../standard/base-types/custom-numeric-format-strings.md).) @@ -164,9 +164,9 @@ Optional. A string that specifies the format of the corresponding argument's res - GUIDs. (See the method.) -However, note that any custom type can implement or extend an existing type's implementation. +However, 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. +The following example uses the `width` and `formatString` arguments to produce formatted output. :::code language="csharp" source="./snippets/System/FormatException/Overview/csharp/formatoverload2.cs" interactive="try-dotnet-method" id="Snippet9"::: :::code language="fsharp" source="./snippets/System/FormatException/Overview/fsharp/formatoverload2.fs" id="Snippet9"::: @@ -178,7 +178,7 @@ Format items are processed sequentially from the beginning of the string. Each f - 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 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. @@ -186,7 +186,7 @@ Format items are processed sequentially from the beginning of the string. Each f 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](#example-an-intercept-provider-and-roman-numeral-formatter). -For more information, see [Processing order](/dotnet/standard/base-types/composite-formatting##processing-order). +For more information, see [Processing order](../../standard/base-types/composite-formatting.md#processing-order). ## Format items that have the same index @@ -208,7 +208,7 @@ The interface has a single member, 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. +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](../../standard/base-types/how-to-define-and-use-custom-numeric-format-providers.md) and . For an example that converts integers to formatted custom numbers, see [Example: A custom formatting operation](#example-a-custom-formatting-operation). For an example that converts unsigned bytes to Roman numerals, see [Example: An intercept provider and Roman numeral formatter](#example-an-intercept-provider-and-roman-numeral-formatter). @@ -225,7 +225,6 @@ This example defines a format provider that formats an integer value as a custom 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="csharp" source="./snippets/System/FormatException/Overview/csharp/interceptor2.cs" id="Snippet11"::: @@ -239,8 +238,7 @@ This example defines a custom format provider that implements 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. +- More readable. Because the expression to insert into a string appears in the interpolated expression rather than in a argument list, interpolated strings are easier to code and to read. Interpolated strings 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. @@ -257,13 +255,9 @@ In contrast, the use of interpolated strings in the following example produces m ### Where can I find the predefined format strings? - For all integral and floating-point types, see [Standard Numeric Format Strings](../../standard/base-types/standard-numeric-format-strings.md) and [Custom Numeric Format Strings](../../standard/base-types/custom-numeric-format-strings.md). - - For date and time values, see [Standard Date and Time Format Strings](../../standard/base-types/standard-date-and-time-format-strings.md) and [Custom Date and Time Format Strings](../../standard/base-types/custom-date-and-time-format-strings.md). - - For enumeration values, see [Enumeration Format Strings](../../standard/base-types/enumeration-format-strings.md). - -- For values, see [Standard TimeSpan Format Strings](../../standard/base-types/standard-timespan-format-strings.md) and [Custom TimeSpan Format Strings](../../standard/base-types/custom-timespan-format-strings.md). - +- For values, see [Standard TimeSpan Format Strings](../../standard/base-types/standard-timespan-format-strings.md) and [Custom TimeSpan Format Strings](../../standard/base-types/custom-timespan-format-strings.md). - For values, see the Remarks section of the reference page. ### How do I control the alignment of the result strings that replace format items? @@ -271,10 +265,10 @@ In contrast, the use of interpolated strings in the following example produces m The general syntax of a format item is: ```txt -{index[,alignment][: formatString]} +{index[,width][: 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. +`width` 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? @@ -292,7 +286,7 @@ If you're using a [custom numeric format string](../../standard/base-types/custo ### 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. +By default, formatting operations only display non-zero integral digits. If you're 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/System/FormatException/Overview/csharp/qa29.cs" interactive="try-dotnet-method" id="Snippet29"::: :::code language="fsharp" source="./snippets/System/FormatException/Overview/fsharp/qa29.fs" id="Snippet29"::: diff --git a/docs/standard/base-types/composite-formatting.md b/docs/standard/base-types/composite-formatting.md index 8a0e69bc93dc6..189b85c720ce3 100644 --- a/docs/standard/base-types/composite-formatting.md +++ b/docs/standard/base-types/composite-formatting.md @@ -2,19 +2,17 @@ title: Composite formatting description: Learn about .NET composite formatting, which takes as input a list of objects and a composite format string, containing fixed text with indexed placeholders. ms.date: 08/07/2023 -ms.custom: devdivchpfy22 ms.topic: conceptual dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "parameter specifiers" - "strings [.NET], alignment" - "format specifiers, composite formatting" - "strings [.NET], composite" - "composite formatting" - "objects [.NET], formatting multiple objects" -ms.assetid: 87b7d528-73f6-43c6-b71a-f23043039a49 --- # Composite formatting @@ -49,13 +47,13 @@ The fixed text is `Name = ` and `, hours = `. The format items are `{0}`, w Each format item takes the following form and consists of the following components: -`{index[,alignment][:formatString]}` +`{index[,width][:formatString]}` The matching braces (`{` and `}`) are required. ### Index component -The mandatory *index* component, which is also called a parameter specifier, is a number starting from 0 that identifies a corresponding item in the list of objects. That is, the format item whose parameter specifier is `0` formats the first object in the list. The format item whose parameter specifier is `1` formats the second object in the list, and so on. The following example includes four parameter specifiers, numbered zero through three, to represent prime numbers less than 10: +The mandatory `index` component, which is also called a parameter specifier, is a number starting from 0 that identifies a corresponding item in the list of objects. That is, the format item whose parameter specifier is `0` formats the first object in the list. The format item whose parameter specifier is `1` formats the second object in the list, and so on. The following example includes four parameter specifiers, numbered zero through three, to represent prime numbers less than 10: :::code language="csharp" source="./snippets/composite-formatting/net/csharp/Program.cs" id="index"::: :::code language="vb" source="./snippets/composite-formatting/net/vb/Program.vb" id="index"::: @@ -67,9 +65,9 @@ Multiple format items can refer to the same element in the list of objects by sp Each format item can refer to any object in the list. For example, if there are three objects, you can format the second, first, and third object by specifying a composite format string such as `{1} {0} {2}`. An object that isn't referenced by a format item is ignored. A is thrown at run time if a parameter specifier designates an item outside the bounds of the list of objects. -### Alignment component +### Width component -The optional *alignment* component is a signed integer indicating the preferred formatted field width. If the value of *alignment* is less than the length of the formatted string, *alignment* is ignored, and the length of the formatted string is used as the field width. The formatted data in the field is right-aligned if *alignment* is positive and left-aligned if *alignment* is negative. If padding is necessary, white space is used. The comma is required if *alignment* is specified. +The optional `width` component is a signed integer indicating the preferred formatted field width. If the value of `width` is less than the length of the formatted string, `width` is ignored, and the length of the formatted string is used as the field width. The formatted data in the field is right-aligned if `width` is positive and left-aligned if `width` is negative. If padding is necessary, white space is used. The comma is required if `width` is specified. The following example defines two arrays, one containing the names of employees and the other containing the hours they worked over two weeks. The composite format string left-aligns the names in a 20-character field and right-aligns their hours in a 5-character field. The "N1" standard format string formats the hours with one fractional digit. @@ -78,13 +76,13 @@ The following example defines two arrays, one containing the names of employees ### Format string component -The optional *formatString* component is a format string that's appropriate for the type of object being formatted. You can specify: +The optional `formatString` component is a format string that's appropriate for the type of object being formatted. You can specify: - A standard or custom numeric format string if the corresponding object is a numeric value. - A standard or custom date and time format string if the corresponding object is a object. - An [enumeration format string](enumeration-format-strings.md) if the corresponding object is an enumeration value. -If *formatString* isn't specified, the general ("G") format specifier for a numeric, date and time, or enumeration type is used. The colon is required if *formatString* is specified. +If `formatString` isn't specified, the general ("G") format specifier for a numeric, date and time, or enumeration type is used. The colon is required if `formatString` is specified. The following table lists types or categories of types in the .NET class library that support a predefined set of format strings, and provides links to the articles that list the supported format strings. String formatting is an extensible mechanism that makes it possible to define new format strings for all existing types and to define a set of format strings supported by an application-defined type. @@ -146,7 +144,7 @@ Each value in the parameter list that corresponds to a format item is converted 1. If the value to be formatted is `null`, an empty string is returned. 1. If an implementation is available, the runtime calls its method. The runtime passes the format item's `formatString` value (or `null` if it's not present) to the method. The runtime also passes the implementation to the method. If the call to the method returns `null`, execution proceeds to the next step. Otherwise, the result of the call is returned. -1. If the value implements the interface, the interface's method is called. If one is present in the format item, the *formatString* value is passed to the method. Otherwise, `null` is passed. The argument is determined as follows: +1. If the value implements the interface, the interface's method is called. If one is present in the format item, the `formatString` value is passed to the method. Otherwise, `null` is passed. The argument is determined as follows: - For a numeric value, if a composite formatting method with a non-null argument is called, the runtime requests a object from its method. If it's unable to supply one, if the value of the argument is `null`, or if the composite formatting method doesn't have an parameter, the object for the current culture is used. - For a date and time value, if a composite formatting method with a non-null argument is called, the runtime requests a object from its method. In the following situations, the object for the current culture is used instead: @@ -180,7 +178,7 @@ The following example demonstrates formatting multiple objects, including format :::code language="csharp" source="./snippets/composite-formatting/net/csharp/Program.cs" id="example_multiple"::: :::code language="vb" source="./snippets/composite-formatting/net/vb/Program.vb" id="example_multiple"::: -The following example demonstrates the use of alignment in formatting. The arguments that are formatted are placed between vertical bar characters (`|`) to highlight the resulting alignment. +The following example demonstrates the use of width in formatting. The arguments that are formatted are placed between vertical bar characters (`|`) to highlight the resulting alignment. :::code language="csharp" source="./snippets/composite-formatting/net/csharp/Program.cs" id="example_bar"::: :::code language="vb" source="./snippets/composite-formatting/net/vb/Program.vb" id="example_bar"::: @@ -191,11 +189,11 @@ The following example demonstrates the use of alignment in formatting. The argum - - [String interpolation (C#)](../../csharp/language-reference/tokens/interpolated.md) - [String interpolation (Visual Basic)](../../visual-basic/programming-guide/language-features/strings/interpolated-strings.md) -- [Formatting Types](formatting-types.md) -- [Standard Numeric Format Strings](standard-numeric-format-strings.md) -- [Custom Numeric Format Strings](custom-numeric-format-strings.md) -- [Standard Date and Time Format Strings](standard-date-and-time-format-strings.md) -- [Custom Date and Time Format Strings](custom-date-and-time-format-strings.md) -- [Standard TimeSpan Format Strings](standard-timespan-format-strings.md) -- [Custom TimeSpan Format Strings](custom-timespan-format-strings.md) -- [Enumeration Format Strings](enumeration-format-strings.md) +- [Formatting types](formatting-types.md) +- [Standard numeric format strings](standard-numeric-format-strings.md) +- [Custom numeric format strings](custom-numeric-format-strings.md) +- [Standard date and time format strings](standard-date-and-time-format-strings.md) +- [Custom date and time format strings](custom-date-and-time-format-strings.md) +- [Standard TimeSpan format strings](standard-timespan-format-strings.md) +- [Custom TimeSpan format strings](custom-timespan-format-strings.md) +- [Enumeration format strings](enumeration-format-strings.md) diff --git a/docs/standard/base-types/creating-new.md b/docs/standard/base-types/creating-new.md index afab18cf73802..8787ed668ac1c 100644 --- a/docs/standard/base-types/creating-new.md +++ b/docs/standard/base-types/creating-new.md @@ -1,86 +1,85 @@ --- -title: "Creating New Strings in .NET" +title: "Creating New Strings" description: Learn to create strings using assignment, class constructors, or System.String methods that combine several strings, arrays of strings, or objects in .NET. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "CopyTo method" - "Join method" - "Format method" - "Concat method" - "strings [.NET], creating" - "Insert method" -ms.assetid: 06fdf123-2fac-4459-8904-eb48ab908a30 --- -# Creating New Strings in .NET - -.NET allows strings to be created using simple assignment, and also overloads a class constructor to support string creation using a number of different parameters. .NET also provides several methods in the class that create new string objects by combining several strings, arrays of strings, or objects. - -## Creating Strings Using Assignment - - The easiest way to create a new object is simply to assign a string literal to a object. - -## Creating Strings Using a Class Constructor - - You can use overloads of the class constructor to create strings from character arrays. You can also create a new string by duplicating a particular character a specified number of times. - -## Methods that Return Strings - - The following table lists several useful methods that return new string objects. - -|Method name|Use| -|-----------------|---------| -||Builds a formatted string from a set of input objects.| -||Builds strings from two or more strings.| -||Builds a new string by combining an array of strings.| -||Builds a new string by inserting a string into the specified index of an existing string.| -||Copies specified characters in a string into a specified position in an array of characters.| - -### Format - - You can use the **String.Format** method to create formatted strings and concatenate strings representing multiple objects. This method automatically converts any passed object into a string. For example, if your application must display an **Int32** value and a **DateTime** value to the user, you can easily construct a string to represent these values using the **Format** method. For information about formatting conventions used with this method, see the section on [composite formatting](composite-formatting.md). - - The following example uses the **Format** method to create a string that uses an integer variable. - +# Create new strings in .NET + +.NET allows strings to be created using simple assignment, and also overloads a class constructor to support string creation using a number of different parameters. .NET also provides several methods in the class that create new string objects by combining several strings, arrays of strings, or objects. + +## Create strings using assignment + + The easiest way to create a new object is simply to assign a string literal to a object. + +## Create strings using a class constructor + + You can use overloads of the class constructor to create strings from character arrays. You can also create a new string by duplicating a particular character a specified number of times. + +## Methods that return strings + + The following table lists several useful methods that return new string objects. + +| Method name | Use | +|-------------------------------------------------------------|--------------------------------------------------------| +| | Builds a formatted string from a set of input objects. | +| | Builds strings from two or more strings. | +| | Builds a new string by combining an array of strings. | +| | Builds a new string by inserting a string into the specified index of an existing string. | +| | Copies specified characters in a string into a specified position in an array of characters. | + +### Format + + You can use the `String.Format` method to create formatted strings and concatenate strings representing multiple objects. This method automatically converts any passed object into a string. For example, if your application must display an `Int32` value and a `DateTime` value to the user, you can easily construct a string to represent these values using the `Format` method. For information about formatting conventions used with this method, see the section on [composite formatting](composite-formatting.md). + + The following example uses the `Format` method to create a string that uses an integer variable. + [!code-csharp[Strings.Creating#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#1)] - [!code-vb[Strings.Creating#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#1)] - - In this example, displays the current date and time in a manner specified by the culture associated with the current thread. - -### Concat - - The **String.Concat** method can be used to easily create a new string object from two or more existing objects. It provides a language-independent way to concatenate strings. This method accepts any class that derives from **System.Object**. The following example creates a string from two existing string objects and a separating character. - + [!code-vb[Strings.Creating#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#1)] + + In this example, displays the current date and time in a manner specified by the culture associated with the current thread. + +### Concat + + The `String.Concat` method can be used to easily create a new string object from two or more existing objects. It provides a language-independent way to concatenate strings. This method accepts any class that derives from `System.Object`. The following example creates a string from two existing string objects and a separating character. + [!code-csharp[Strings.Creating#2](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#2)] - [!code-vb[Strings.Creating#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#2)] - -### Join - - The **String.Join** method creates a new string from an array of strings and a separator string. This method is useful if you want to concatenate multiple strings together, making a list perhaps separated by a comma. - - The following example uses a space to bind a string array. - + [!code-vb[Strings.Creating#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#2)] + +### Join + + The `String.Join` method creates a new string from an array of strings and a separator string. This method is useful if you want to concatenate multiple strings together, making a list perhaps separated by a comma. + + The following example uses a space to bind a string array. + [!code-csharp[Strings.Creating#3](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#3)] - [!code-vb[Strings.Creating#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#3)] - -### Insert + [!code-vb[Strings.Creating#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#3)] + +### Insert + + The `String.Insert` method creates a new string by inserting a string into a specified position in another string. This method uses a zero-based index. The following example inserts a string into the fifth index position of `MyString` and creates a new string with this value. - The **String.Insert** method creates a new string by inserting a string into a specified position in another string. This method uses a zero-based index. The following example inserts a string into the fifth index position of `MyString` and creates a new string with this value. - [!code-csharp[Strings.Creating#4](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#4)] - [!code-vb[Strings.Creating#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#4)] - -### CopyTo - - The **String.CopyTo** method copies portions of a string into an array of characters. You can specify both the beginning index of the string and the number of characters to be copied. This method takes the source index, an array of characters, the destination index, and the number of characters to copy. All indexes are zero-based. - - The following example uses the **CopyTo** method to copy the characters of the word "Hello" from a string object to the first index position of an array of characters. - + [!code-vb[Strings.Creating#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#4)] + +### CopyTo + + The `String.CopyTo` method copies portions of a string into an array of characters. You can specify both the beginning index of the string and the number of characters to be copied. This method takes the source index, an array of characters, the destination index, and the number of characters to copy. All indexes are zero-based. + + The following example uses the `CopyTo` method to copy the characters of the word "Hello" from a string object to the first index position of an array of characters. + [!code-csharp[Strings.Creating#5](../../../samples/snippets/csharp/VS_Snippets_CLR/Strings.Creating/cs/Example.cs#5)] - [!code-vb[Strings.Creating#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#5)] - + [!code-vb[Strings.Creating#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Strings.Creating/vb/Example.vb#5)] + ## See also - [Basic String Operations](basic-string-operations.md) diff --git a/docs/standard/base-types/formatting-types.md b/docs/standard/base-types/formatting-types.md index 11e44f634795e..e83111a46a285 100644 --- a/docs/standard/base-types/formatting-types.md +++ b/docs/standard/base-types/formatting-types.md @@ -296,7 +296,7 @@ The following example instantiates a `Temperature` object. It then calls the and , support composite formatting. A composite format string is a kind of template that returns a single string that incorporates the string representation of zero, one, or more objects. Each object is represented in the composite format string by an indexed format item. The index of the format item corresponds to the position of the object that it represents in the method's parameter list. Indexes are zero-based. For example, in the following call to the method, the first format item, `{0:D}`, is replaced by the string representation of `thatDate`; the second format item, `{1}`, is replaced by the string representation of `item1`; and the third format item, `{2:C2}`, is replaced by the string representation of `item1.Value`. +Some methods, such as and , support *composite formatting*. A composite format string is a kind of template that returns a single string that incorporates the string representation of zero, one, or more objects. Each object is represented in the composite format string by an indexed format item. The index of the format item corresponds to the position of the object that it represents in the method's parameter list. Indexes are zero-based. For example, in the following call to the method, the first format item, `{0:D}`, is replaced by the string representation of `thatDate`; the second format item, `{1}`, is replaced by the string representation of `item1`; and the third format item, `{2:C2}`, is replaced by the string representation of `item1.Value`. [!code-csharp[Conceptual.Formatting.Overview#14](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.formatting.overview/cs/composite1.cs#14)] [!code-vb[Conceptual.Formatting.Overview#14](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.formatting.overview/vb/composite1.vb#14)] @@ -307,10 +307,10 @@ In addition to replacing a format item with the string representation of its cor - The width of the field that contains the object's string representation, and the alignment of the string representation in that field. You do this by following the format item's index with a `,` (comma) followed the field width. The string is right-aligned in the field if the field width is a positive value, and it is left-aligned if the field width is a negative value. The following example left-aligns date values in a 20-character field, and it right-aligns decimal values with one fractional digit in an 11-character field. - [!code-csharp[Conceptual.Formatting.Overview#22](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.formatting.overview/cs/composite2.cs#22)] - [!code-vb[Conceptual.Formatting.Overview#22](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.formatting.overview/vb/composite2.vb#22)] + [!code-csharp[Conceptual.Formatting.Overview#22](../../../samples/snippets/csharp/VS_Snippets_CLR/conceptual.formatting.overview/cs/composite2.cs#22)] + [!code-vb[Conceptual.Formatting.Overview#22](../../../samples/snippets/visualbasic/VS_Snippets_CLR/conceptual.formatting.overview/vb/composite2.vb#22)] - Note that, if both the alignment string component and the format string component are present, the former precedes the latter (for example, `{0,-20:g}`. + If both the alignment string component and the format string component are present, the former precedes the latter (for example, `{0,-20:g}`). For more information about composite formatting, see [Composite Formatting](composite-formatting.md). diff --git a/docs/standard/base-types/how-to-pad-a-number-with-leading-zeros.md b/docs/standard/base-types/how-to-pad-a-number-with-leading-zeros.md index ceffc018e7daa..df5a9b4abb282 100644 --- a/docs/standard/base-types/how-to-pad-a-number-with-leading-zeros.md +++ b/docs/standard/base-types/how-to-pad-a-number-with-leading-zeros.md @@ -82,7 +82,6 @@ The following example formats several numeric values with leading zeros. As a re 1. Create a custom format string that uses: - The zero placeholder ("0") for each of the leading zeros to appear in the string. - - Either the zero placeholder or the digit placeholder "#" to represent each digit in the default string. 1. Supply the custom format string as a parameter either to the number's `ToString(String)` method or to a method that supports composite formatting. diff --git a/docs/standard/base-types/miscellaneous-constructs-in-regular-expressions.md b/docs/standard/base-types/miscellaneous-constructs-in-regular-expressions.md index fcc1c61c943f2..28d8dea1bdb38 100644 --- a/docs/standard/base-types/miscellaneous-constructs-in-regular-expressions.md +++ b/docs/standard/base-types/miscellaneous-constructs-in-regular-expressions.md @@ -3,10 +3,10 @@ description: "Learn more about: Miscellaneous Constructs in Regular Expressions" title: "Miscellaneous Constructs in Regular Expressions" ms.date: "03/30/2017" ms.topic: conceptual -dev_langs: +dev_langs: - "csharp" - "vb" -helpviewer_keywords: +helpviewer_keywords: - "constructs, miscellaneous" - ".NET regular expressions, miscellaneous constructs" - "regular expressions, miscellaneous constructs" @@ -14,88 +14,88 @@ ms.assetid: 7d10d11f-680f-4721-b047-fb136316b4cd --- # Miscellaneous Constructs in Regular Expressions -Regular expressions in .NET include three miscellaneous language constructs. One lets you enable or disable particular matching options in the middle of a regular expression pattern. The remaining two let you include comments in a regular expression. - -## Inline Options - - You can set or disable specific pattern matching options for part of a regular expression by using the syntax - -`(?imnsx-imnsx)` - - You list the options you want to enable after the question mark, and the options you want to disable after the minus sign. The following table describes each option. For more information about each option, see [Regular Expression Options](regular-expression-options.md). - -|Option|Description| -|------------|-----------------| -|`i`|Case-insensitive matching.| -|`m`|Multiline mode.| -|`n`|Explicit captures only. (Parentheses do not act as capturing groups.)| -|`s`|Single-line mode.| -|`x`|Ignore unescaped white space, and allow x-mode comments.| - - Any change in regular expression options defined by the `(?imnsx-imnsx)` construct remains in effect until the end of the enclosing group. - +Regular expressions in .NET include three miscellaneous language constructs. One lets you enable or disable particular matching options in the middle of a regular expression pattern. The remaining two let you include comments in a regular expression. + +## Inline Options + + You can set or disable specific pattern matching options for part of a regular expression by using the syntax + +`(?imnsx-imnsx)` + + You list the options you want to enable after the question mark, and the options you want to disable after the minus sign. The following table describes each option. For more information about each option, see [Regular Expression Options](regular-expression-options.md). + +|Option|Description| +|------------|-----------------| +|`i`|Case-insensitive matching.| +|`m`|Multiline mode.| +|`n`|Explicit captures only. (Parentheses do not act as capturing groups.)| +|`s`|Single-line mode.| +|`x`|Ignore unescaped white space, and allow x-mode comments.| + + Any change in regular expression options defined by the `(?imnsx-imnsx)` construct remains in effect until the end of the enclosing group. + > [!NOTE] -> The `(?imnsx-imnsx:`*subexpression*`)` grouping construct provides identical functionality for a subexpression. For more information, see [Grouping Constructs](grouping-constructs-in-regular-expressions.md). - - The following example uses the `i`, `n`, and `x` options to enable case insensitivity and explicit captures, and to ignore white space in the regular expression pattern in the middle of a regular expression. - +> The `(?imnsx-imnsx:`*subexpression*`)` grouping construct provides identical functionality for a subexpression. For more information, see [Grouping Constructs](grouping-constructs-in-regular-expressions.md). + + The following example uses the `i`, `n`, and `x` options to enable case insensitivity and explicit captures, and to ignore white space in the regular expression pattern in the middle of a regular expression. + [!code-csharp[RegularExpressions.Language.Miscellaneous#1](../../../samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.miscellaneous/cs/miscellaneous1.cs#1)] - [!code-vb[RegularExpressions.Language.Miscellaneous#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.miscellaneous/vb/miscellaneous1.vb#1)] - - The example defines two regular expressions. The first, `\b(D\w+)\s(d\w+)\b`, matches two consecutive words that begin with an uppercase "D" and a lowercase "d". The second regular expression, `\b(D\w+)(?ixn) \s (d\w+) \b`, uses inline options to modify this pattern, as described in the following table. A comparison of the results confirms the effect of the `(?ixn)` construct. - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Start at a word boundary.| -|`(D\w+)`|Match a capital "D" followed by one or more word characters. This is the first capture group.| -|`(?ixn)`|From this point on, make comparisons case-insensitive, make only explicit captures, and ignore white space in the regular expression pattern.| -|`\s`|Match a white-space character.| -|`(d\w+)`|Match an uppercase or lowercase "d" followed by one or more word characters. This group is not captured because the `n` (explicit capture) option was enabled.| -|`\b`|Match a word boundary.| - -## Inline Comment - - The `(?#` *comment*`)` construct lets you include an inline comment in a regular expression. The regular expression engine does not use any part of the comment in pattern matching, although the comment is included in the string that is returned by the method. The comment ends at the first closing parenthesis. - - The following example repeats the first regular expression pattern from the example in the previous section. It adds two inline comments to the regular expression to indicate whether the comparison is case-sensitive. The regular expression pattern, `\b((?# case-sensitive comparison)D\w+)\s(?ixn)((?#case-insensitive comparison)d\w+)\b`, is defined as follows. - -|Pattern|Description| -|-------------|-----------------| -|`\b`|Start at a word boundary.| -|`(?# case-sensitive comparison)`|A comment. It does not affect pattern-matching behavior.| -|`(D\w+)`|Match a capital "D" followed by one or more word characters. This is the first capturing group.| -|`\s`|Match a white-space character.| -|`(?ixn)`|From this point on, make comparisons case-insensitive, make only explicit captures, and ignore white space in the regular expression pattern.| -|`(?#case-insensitive comparison)`|A comment. It does not affect pattern-matching behavior.| -|`(d\w+)`|Match an uppercase or lowercase "d" followed by one or more word characters. This is the second capture group.| -|`\b`|Match a word boundary.| - + [!code-vb[RegularExpressions.Language.Miscellaneous#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.miscellaneous/vb/miscellaneous1.vb#1)] + + The example defines two regular expressions. The first, `\b(D\w+)\s(d\w+)\b`, matches two consecutive words that begin with an uppercase "D" and a lowercase "d". The second regular expression, `\b(D\w+)(?ixn) \s (d\w+) \b`, uses inline options to modify this pattern, as described in the following table. A comparison of the results confirms the effect of the `(?ixn)` construct. + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Start at a word boundary.| +|`(D\w+)`|Match a capital "D" followed by one or more word characters. This is the first capture group.| +|`(?ixn)`|From this point on, make comparisons case-insensitive, make only explicit captures, and ignore white space in the regular expression pattern.| +|`\s`|Match a white-space character.| +|`(d\w+)`|Match an uppercase or lowercase "d" followed by one or more word characters. This group is not captured because the `n` (explicit capture) option was enabled.| +|`\b`|Match a word boundary.| + +## Inline Comment + + The `(?#` *comment*`)` construct lets you include an inline comment in a regular expression. The regular expression engine does not use any part of the comment in pattern matching, although the comment is included in the string that is returned by the method. The comment ends at the first closing parenthesis. + + The following example repeats the first regular expression pattern from the example in the previous section. It adds two inline comments to the regular expression to indicate whether the comparison is case-sensitive. The regular expression pattern, `\b((?# case-sensitive comparison)D\w+)\s(?ixn)((?#case-insensitive comparison)d\w+)\b`, is defined as follows. + +|Pattern|Description| +|-------------|-----------------| +|`\b`|Start at a word boundary.| +|`(?# case-sensitive comparison)`|A comment. It does not affect pattern-matching behavior.| +|`(D\w+)`|Match a capital "D" followed by one or more word characters. This is the first capturing group.| +|`\s`|Match a white-space character.| +|`(?ixn)`|From this point on, make comparisons case-insensitive, make only explicit captures, and ignore white space in the regular expression pattern.| +|`(?#case-insensitive comparison)`|A comment. It does not affect pattern-matching behavior.| +|`(d\w+)`|Match an uppercase or lowercase "d" followed by one or more word characters. This is the second capture group.| +|`\b`|Match a word boundary.| + [!code-csharp[RegularExpressions.Language.Miscellaneous#2](../../../samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.miscellaneous/cs/miscellaneous2.cs#2)] - [!code-vb[RegularExpressions.Language.Miscellaneous#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.miscellaneous/vb/miscellaneous2.vb#2)] - -## End-of-Line Comment - - A number sign (`#`) marks an x-mode comment, which starts at the unescaped # character at the end of the regular expression pattern and continues until the end of the line. To use this construct, you must either enable the `x` option (through inline options) or supply the value to the `option` parameter when instantiating the object or calling a static method. - - The following example illustrates the end-of-line comment construct. It determines whether a string is a composite format string that includes at least one format item. The following table describes the constructs in the regular expression pattern: - - `\{\d+(,-*\d+)*(\:\w{1,4}?)*\}(?x) # Looks for a composite format item.` - -|Pattern|Description| -|-------------|-----------------| -|`\{`|Match an opening brace.| -|`\d+`|Match one or more decimal digits.| -|`(,-*\d+)*`|Match zero or one occurrence of a comma, followed by an optional minus sign, followed by one or more decimal digits.| -|`(\:\w{1,4}?)*`|Match zero or one occurrence of a colon, followed by one to four, but as few as possible, white-space characters.| -|`\}`|Match a closing brace.| -|`(?x)`|Enable the ignore pattern white-space option so that the end-of-line comment will be recognized.| -|`# Looks for a composite format item.`|An end-of-line comment.| - + [!code-vb[RegularExpressions.Language.Miscellaneous#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.miscellaneous/vb/miscellaneous2.vb#2)] + +## End-of-Line Comment + + A number sign (`#`) marks an x-mode comment, which starts at the unescaped # character at the end of the regular expression pattern and continues until the end of the line. To use this construct, you must either enable the `x` option (through inline options) or supply the value to the `option` parameter when instantiating the object or calling a static method. + + The following example illustrates the end-of-line comment construct. It determines whether a string is a composite format string that includes at least one format item. The following table describes the constructs in the regular expression pattern: + + `\{\d+(,-*\d+)*(\:\w{1,4}?)*\}(?x) # Looks for a composite format item.` + +| Pattern | Description | +|-------------|-----------------------------------| +| `\{` | Match an opening brace. | +| `\d+` | Match one or more decimal digits. | +| `(,-*\d+)*` | Match zero or one occurrence of a comma, followed by an optional minus sign, followed by one or more decimal digits. | +| `(\:\w{1,4}?)*` | Match zero or one occurrence of a colon, followed by one to four, but as few as possible, white-space characters. | +| `\}` | Match a closing brace. | +| `(?x)` | Enable the ignore pattern white-space option so that the end-of-line comment will be recognized. | +| `# Looks for a composite format item.` | An end-of-line comment. | + [!code-csharp[RegularExpressions.Language.Miscellaneous#3](../../../samples/snippets/csharp/VS_Snippets_CLR/regularexpressions.language.miscellaneous/cs/miscellaneous3.cs#3)] - [!code-vb[RegularExpressions.Language.Miscellaneous#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.miscellaneous/vb/miscellaneous3.vb#3)] - - Note that, instead of providing the `(?x)` construct in the regular expression, the comment could also have been recognized by calling the method and passing it the enumeration value. - + [!code-vb[RegularExpressions.Language.Miscellaneous#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/regularexpressions.language.miscellaneous/vb/miscellaneous3.vb#3)] + + Note that, instead of providing the `(?x)` construct in the regular expression, the comment could also have been recognized by calling the method and passing it the enumeration value. + ## See also - [Regular Expression Language - Quick Reference](regular-expression-language-quick-reference.md) diff --git a/docs/standard/base-types/standard-numeric-format-strings.md b/docs/standard/base-types/standard-numeric-format-strings.md index f5f5afa0fdfc9..199aca156878d 100644 --- a/docs/standard/base-types/standard-numeric-format-strings.md +++ b/docs/standard/base-types/standard-numeric-format-strings.md @@ -31,7 +31,7 @@ Standard numeric format strings are used to format common numeric types. A stand - **On .NET Core 2.1 and later**, the runtime selects the result with an even least significant digit (that is, using ). > [!NOTE] - > The precision specifier determines the number of digits in the result string. To pad a result string with leading or trailing spaces, use the [composite formatting](composite-formatting.md) feature and define an *alignment component* in the format item. + > The precision specifier determines the number of digits in the result string. To pad a result string with leading or trailing spaces, use the [composite formatting](composite-formatting.md) feature and define a *width component* in the format item. Standard numeric format strings are supported by: @@ -53,7 +53,7 @@ The following table describes the standard numeric format specifiers and display > The result of a formatted string for a specific culture might differ from the following examples. Operating system settings, user settings, environment variables, and the .NET version you're using can all affect the format. For example, starting with .NET 5, .NET tries to unify cultural formats across platforms. For more information, see [.NET globalization and ICU](../../core/extensions/globalization-icu.md). | Format specifier | Name | Description | Examples | -|--|--|--|--| +|------------------|------|-------------|----------| | "B" or "b" | Binary | Result: A binary string.

Supported by: Integral types only (.NET 8+).

Precision specifier: Number of digits in the result string.

More information: [The Binary ("B") Format Specifier](#BFormatString). | 42 ("B")
-> 101010

255 ("b16")
-> 0000000011111111 | | "C" or "c" | Currency | Result: A currency value.

Supported by: All numeric types.

Precision specifier: Number of decimal digits.

Default precision specifier: Defined by .

More information: [The Currency ("C") Format Specifier](#CFormatString). | 123.456 ("C", en-US)
-> \\$123.46

123.456 ("C", fr-FR)
-> 123,46 €

123.456 ("C", ja-JP)
-> ¥123

-123.456 ("C3", en-US)
-> (\\$123.456)

-123.456 ("C3", fr-FR)
-> -123,456 €

-123.456 ("C3", ja-JP)
-> -¥123.456 | | "D" or "d" | Decimal | Result: Integer digits with optional negative sign.

Supported by: Integral types only.

Precision specifier: Minimum number of digits.

Default precision specifier: Minimum number of digits required.

More information: [The Decimal("D") Format Specifier](#DFormatString). | 1234 ("D")
-> 1234

-1234 ("D6")
-> -001234 | diff --git a/docs/standard/base-types/stringbuilder.md b/docs/standard/base-types/stringbuilder.md index 60c9818b95358..dc07b09d28c96 100644 --- a/docs/standard/base-types/stringbuilder.md +++ b/docs/standard/base-types/stringbuilder.md @@ -2,11 +2,11 @@ title: "Using the StringBuilder Class in .NET" description: Learn how to use the StringBuilder class in .NET. Use this class to modify a string without creating a new object. ms.date: "03/30/2017" -dev_langs: +dev_langs: - "csharp" - "vb" - "cpp" -helpviewer_keywords: +helpviewer_keywords: - "Remove method" - "strings [.NET], capacities" - "StringBuilder object" @@ -19,101 +19,101 @@ ms.assetid: 5c14867c-9a99-45bc-ae7f-2686700d377a --- # Using the StringBuilder Class in .NET -The object is immutable. Every time you use one of the methods in the class, you create a new string object in memory, which requires a new allocation of space for that new object. In situations where you need to perform repeated modifications to a string, the overhead associated with creating a new object can be costly. The class can be used when you want to modify a string without creating a new object. For example, using the class can boost performance when concatenating many strings together in a loop. - -## Importing the System.Text Namespace +The object is immutable. Every time you use one of the methods in the class, you create a new string object in memory, which requires a new allocation of space for that new object. In situations where you need to perform repeated modifications to a string, the overhead associated with creating a new object can be costly. The class can be used when you want to modify a string without creating a new object. For example, using the class can boost performance when concatenating many strings together in a loop. + +## Importing the System.Text Namespace + + The class is found in the namespace. To avoid having to provide a fully qualified type name in your code, you can import the namespace: - The class is found in the namespace. To avoid having to provide a fully qualified type name in your code, you can import the namespace: - [!code-cpp[Conceptual.StringBuilder#11](../../../samples/snippets/cpp/VS_Snippets_CLR/Conceptual.StringBuilder/cpp/example.cpp#11)] [!code-csharp[Conceptual.StringBuilder#11](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.StringBuilder/cs/Example.cs#11)] - [!code-vb[Conceptual.StringBuilder#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#11)] - -## Instantiating a StringBuilder Object + [!code-vb[Conceptual.StringBuilder#11](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#11)] + +## Instantiating a StringBuilder Object + + You can create a new instance of the class by initializing your variable with one of the overloaded constructor methods, as illustrated in the following example. - You can create a new instance of the class by initializing your variable with one of the overloaded constructor methods, as illustrated in the following example. - [!code-cpp[Conceptual.StringBuilder#1](../../../samples/snippets/cpp/VS_Snippets_CLR/Conceptual.StringBuilder/cpp/example.cpp#1)] [!code-csharp[Conceptual.StringBuilder#1](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.StringBuilder/cs/Example.cs#1)] - [!code-vb[Conceptual.StringBuilder#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#1)] - -## Setting the Capacity and Length + [!code-vb[Conceptual.StringBuilder#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#1)] + +## Setting the Capacity and Length + + Although the is a dynamic object that allows you to expand the number of characters in the string that it encapsulates, you can specify a value for the maximum number of characters that it can hold. This value is called the capacity of the object and should not be confused with the length of the string that the current holds. For example, you might create a new instance of the class with the string "Hello", which has a length of 5, and you might specify that the object has a maximum capacity of 25. When you modify the , it does not reallocate size for itself until the capacity is reached. When this occurs, the new space is allocated automatically and the capacity is doubled. You can specify the capacity of the class using one of the overloaded constructors. The following example specifies that the `myStringBuilder` object can be expanded to a maximum of 25 spaces. - Although the is a dynamic object that allows you to expand the number of characters in the string that it encapsulates, you can specify a value for the maximum number of characters that it can hold. This value is called the capacity of the object and should not be confused with the length of the string that the current holds. For example, you might create a new instance of the class with the string "Hello", which has a length of 5, and you might specify that the object has a maximum capacity of 25. When you modify the , it does not reallocate size for itself until the capacity is reached. When this occurs, the new space is allocated automatically and the capacity is doubled. You can specify the capacity of the class using one of the overloaded constructors. The following example specifies that the `myStringBuilder` object can be expanded to a maximum of 25 spaces. - [!code-cpp[Conceptual.StringBuilder#2](../../../samples/snippets/cpp/VS_Snippets_CLR/Conceptual.StringBuilder/cpp/example.cpp#2)] [!code-csharp[Conceptual.StringBuilder#2](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.StringBuilder/cs/Example.cs#2)] - [!code-vb[Conceptual.StringBuilder#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#2)] - - Additionally, you can use the read/write property to set the maximum length of your object. The following example uses the **Capacity** property to define the maximum object length. - + [!code-vb[Conceptual.StringBuilder#2](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#2)] + + Additionally, you can use the read/write property to set the maximum length of your object. The following example uses the **Capacity** property to define the maximum object length. + [!code-cpp[Conceptual.StringBuilder#3](../../../samples/snippets/cpp/VS_Snippets_CLR/Conceptual.StringBuilder/cpp/example.cpp#3)] [!code-csharp[Conceptual.StringBuilder#3](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.StringBuilder/cs/Example.cs#3)] - [!code-vb[Conceptual.StringBuilder#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#3)] - - The method can be used to check the capacity of the current **StringBuilder**. If the capacity is greater than the passed value, no change is made; however, if the capacity is smaller than the passed value, the current capacity is changed to match the passed value. - - The property can also be viewed or set. If you set the **Length** property to a value that is greater than the **Capacity** property, the **Capacity** property is automatically changed to the same value as the **Length** property. Setting the **Length** property to a value that is less than the length of the string within the current **StringBuilder** shortens the string. - -## Modifying the StringBuilder String - - The following table lists the methods you can use to modify the contents of a **StringBuilder**. - -|Method name|Use| -|-----------------|---------| -||Appends information to the end of the current **StringBuilder**.| -||Replaces a format specifier passed in a string with formatted text.| -||Inserts a string or object into the specified index of the current **StringBuilder**.| -||Removes a specified number of characters from the current **StringBuilder**.| -||Replaces all occurrences of a specified character or string in the current **StringBuilder** with another specified character or string.| - -### Append - - The **Append** method can be used to add text or a string representation of an object to the end of a string represented by the current **StringBuilder**. The following example initializes a **StringBuilder** to "Hello World" and then appends some text to the end of the object. Space is allocated automatically as needed. - + [!code-vb[Conceptual.StringBuilder#3](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#3)] + + The method can be used to check the capacity of the current **StringBuilder**. If the capacity is greater than the passed value, no change is made; however, if the capacity is smaller than the passed value, the current capacity is changed to match the passed value. + + The property can also be viewed or set. If you set the **Length** property to a value that is greater than the **Capacity** property, the **Capacity** property is automatically changed to the same value as the **Length** property. Setting the **Length** property to a value that is less than the length of the string within the current **StringBuilder** shortens the string. + +## Modifying the StringBuilder String + + The following table lists the methods you can use to modify the contents of a **StringBuilder**. + +|Method name|Use| +|-----------------|---------| +||Appends information to the end of the current **StringBuilder**.| +||Replaces a format specifier passed in a string with formatted text.| +||Inserts a string or object into the specified index of the current **StringBuilder**.| +||Removes a specified number of characters from the current **StringBuilder**.| +||Replaces all occurrences of a specified character or string in the current **StringBuilder** with another specified character or string.| + +### Append + + The **Append** method can be used to add text or a string representation of an object to the end of a string represented by the current **StringBuilder**. The following example initializes a **StringBuilder** to "Hello World" and then appends some text to the end of the object. Space is allocated automatically as needed. + [!code-cpp[Conceptual.StringBuilder#4](../../../samples/snippets/cpp/VS_Snippets_CLR/Conceptual.StringBuilder/cpp/example.cpp#4)] [!code-csharp[Conceptual.StringBuilder#4](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.StringBuilder/cs/Example.cs#4)] - [!code-vb[Conceptual.StringBuilder#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#4)] - -### AppendFormat + [!code-vb[Conceptual.StringBuilder#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#4)] + +### AppendFormat + + The method adds text to the end of the object. It supports the [composite formatting feature](composite-formatting.md) by calling the implementation of the object or objects to be formatted. Therefore, it accepts the standard format strings for numeric, date and time, and enumeration values, the custom format strings for numeric and date and time values, and the format strings defined for custom types. (For information about formatting, see [Formatting Types](formatting-types.md).) You can use this method to customize the format of variables and append those values to a . The following example uses the method to place an integer value formatted as a currency value at the end of a object. - The method adds text to the end of the object. It supports the composite formatting feature (for more information, see [Composite Formatting](composite-formatting.md)) by calling the implementation of the object or objects to be formatted. Therefore, it accepts the standard format strings for numeric, date and time, and enumeration values, the custom format strings for numeric and date and time values, and the format strings defined for custom types. (For information about formatting, see [Formatting Types](formatting-types.md).) You can use this method to customize the format of variables and append those values to a . The following example uses the method to place an integer value formatted as a currency value at the end of a object. - [!code-cpp[Conceptual.StringBuilder#5](../../../samples/snippets/cpp/VS_Snippets_CLR/Conceptual.StringBuilder/cpp/example.cpp#5)] [!code-csharp[Conceptual.StringBuilder#5](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.StringBuilder/cs/Example.cs#5)] - [!code-vb[Conceptual.StringBuilder#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#5)] - -### Insert + [!code-vb[Conceptual.StringBuilder#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#5)] + +### Insert + + The method adds a string or object to a specified position in the current object. The following example uses this method to insert a word into the sixth position of a object. - The method adds a string or object to a specified position in the current object. The following example uses this method to insert a word into the sixth position of a object. - [!code-cpp[Conceptual.StringBuilder#6](../../../samples/snippets/cpp/VS_Snippets_CLR/Conceptual.StringBuilder/cpp/example.cpp#6)] [!code-csharp[Conceptual.StringBuilder#6](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.StringBuilder/cs/Example.cs#6)] - [!code-vb[Conceptual.StringBuilder#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#6)] - -### Remove + [!code-vb[Conceptual.StringBuilder#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#6)] + +### Remove + + You can use the **Remove** method to remove a specified number of characters from the current object, beginning at a specified zero-based index. The following example uses the **Remove** method to shorten a object. - You can use the **Remove** method to remove a specified number of characters from the current object, beginning at a specified zero-based index. The following example uses the **Remove** method to shorten a object. - [!code-cpp[Conceptual.StringBuilder#7](../../../samples/snippets/cpp/VS_Snippets_CLR/Conceptual.StringBuilder/cpp/example.cpp#7)] [!code-csharp[Conceptual.StringBuilder#7](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.StringBuilder/cs/Example.cs#7)] - [!code-vb[Conceptual.StringBuilder#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#7)] - -### Replace + [!code-vb[Conceptual.StringBuilder#7](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#7)] + +### Replace + + The **Replace** method can be used to replace characters within the object with another specified character. The following example uses the **Replace** method to search a object for all instances of the exclamation point character (!) and replace them with the question mark character (?). - The **Replace** method can be used to replace characters within the object with another specified character. The following example uses the **Replace** method to search a object for all instances of the exclamation point character (!) and replace them with the question mark character (?). - [!code-cpp[Conceptual.StringBuilder#8](../../../samples/snippets/cpp/VS_Snippets_CLR/Conceptual.StringBuilder/cpp/example.cpp#8)] [!code-csharp[Conceptual.StringBuilder#8](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.StringBuilder/cs/Example.cs#8)] - [!code-vb[Conceptual.StringBuilder#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#8)] - -## Converting a StringBuilder Object to a String + [!code-vb[Conceptual.StringBuilder#8](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/Example.vb#8)] + +## Converting a StringBuilder Object to a String + + You must convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. You do this conversion by calling the method. The following example calls a number of methods and then calls the method to display the string. - You must convert the object to a object before you can pass the string represented by the object to a method that has a parameter or display it in the user interface. You do this conversion by calling the method. The following example calls a number of methods and then calls the method to display the string. - [!code-csharp[Conceptual.StringBuilder#10](../../../samples/snippets/csharp/VS_Snippets_CLR/Conceptual.StringBuilder/cs/tostringexample1.cs#10)] - [!code-vb[Conceptual.StringBuilder#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/tostringexample1.vb#10)] - + [!code-vb[Conceptual.StringBuilder#10](../../../samples/snippets/visualbasic/VS_Snippets_CLR/Conceptual.StringBuilder/vb/tostringexample1.vb#10)] + ## See also - diff --git a/docs/visual-basic/language-reference/special-characters/interpolated.md b/docs/visual-basic/language-reference/special-characters/interpolated.md index e1b89de5c21a5..c0caf869fb970 100644 --- a/docs/visual-basic/language-reference/special-characters/interpolated.md +++ b/docs/visual-basic/language-reference/special-characters/interpolated.md @@ -5,7 +5,7 @@ ms.date: 10/31/2017 --- # $ (Visual Basic Reference) -Identifies a string literal as an [interpolated string](../../programming-guide/language-features/strings/interpolated-strings.md). An interpolated string is a template-like string that contains literal text along with *interpolated expressions*. An interpolated expression is an expression that produces a result to be formatted in the resultant string. When the interpolated string is resolved, for example in an assignment statement or a method call, its interpolated expressions are replaced by their string representations in the result string. Interpolated strings are replacements for the [composite format strings](../../../standard/base-types/composite-formatting.md) supported by the .NET Framework. +Identifies a string literal as an [interpolated string](../../programming-guide/language-features/strings/interpolated-strings.md). An interpolated string is a template-like string that contains literal text along with *interpolated expressions*. An interpolated expression is an expression that produces a result to be formatted in the resultant string. When the interpolated string is resolved, for example in an assignment statement or a method call, its interpolated expressions are replaced by their string representations in the result string. Interpolated strings are replacements for the [composite format strings](../../../standard/base-types/composite-formatting.md) supported by .NET. The following example uses the `$` character to define an interpolated string. diff --git a/docs/visual-basic/programming-guide/language-features/strings/interpolated-strings.md b/docs/visual-basic/programming-guide/language-features/strings/interpolated-strings.md index 18eba0d623e32..a2561699805e3 100644 --- a/docs/visual-basic/programming-guide/language-features/strings/interpolated-strings.md +++ b/docs/visual-basic/programming-guide/language-features/strings/interpolated-strings.md @@ -3,17 +3,17 @@ description: "Learn more about: Interpolated Strings (Visual Basic Reference)" title: "Interpolated Strings" ms.date: "10/31/2017" --- -# Interpolated Strings (Visual Basic Reference) +# Interpolated strings (Visual Basic Reference) -Used to construct strings. An interpolated string looks like a template string that contains *interpolated expressions*. An interpolated string returns a string that replaces the interpolated expressions that it contains with their string representations. This feature is available in Visual Basic 14 and later versions. +Used to construct strings. An interpolated string looks like a template string that contains *interpolated expressions*. An interpolated string returns a string that replaces the interpolated expressions that it contains with their string representations. This feature is available in Visual Basic 14 and later versions. -The arguments of an interpolated string are easier to understand than a [composite format string](../../../../standard/base-types/composite-formatting.md#composite-format-string). For example, the interpolated string +The arguments of an interpolated string are easier to understand than a [composite format string](../../../../standard/base-types/composite-formatting.md#composite-format-string). For example, the following interpolated string contains two interpolated expressions, `{name}` and `{hours:hh}`: ```vb Console.WriteLine($"Name = {name}, hours = {hours:hh}") ``` -contains two interpolated expressions, '{name}' and '{hours:hh}'. The equivalent composite format string is: +The equivalent composite format string is: ```vb Console.WriteLine("Name = {0}, hours = {1:hh}", name, hours) @@ -25,24 +25,24 @@ The structure of an interpolated string is: $" { [,] [:] } ..." ``` -where: +Where: -- *field-width* is a signed integer that indicates the number of characters in the field. If it is positive, the field is right-aligned; if negative, left-aligned. +- `field-width` is a signed integer that indicates the number of characters in the field. If it's positive, the field is right-aligned; if negative, left-aligned. -- *format-string* is a format string appropriate for the type of object being formatted. For example, for a value, it could be a [standard date and time format string](../../../../standard/base-types/standard-date-and-time-format-strings.md) such as "D" or "d". +- `format-string` is a format string appropriate for the type of object being formatted. For example, for a value, it could be a [standard date and time format string](../../../../standard/base-types/standard-date-and-time-format-strings.md) such as "D" or "d". > [!IMPORTANT] -> You cannot have any white space between the `$` and the `"` that starts the string. Doing so causes a compiler error. +> You can't have any white space between the `$` and the `"` that starts the string. Doing so causes a compiler error. -You can use an interpolated string anywhere you can use a string literal. The interpolated string is evaluated each time the code with the interpolated string executes. This allows you to separate the definition and evaluation of an interpolated string. +You can use an interpolated string anywhere you can use a string literal. The interpolated string is evaluated each time the code with the interpolated string executes. This allows you to separate the definition and evaluation of an interpolated string. -To include a curly brace ("{" or "}") in an interpolated string, use two curly braces, "{{" or "}}". See the Implicit Conversions section for more details. +To include a curly brace ("{" or "}") in an interpolated string, use two curly braces, "{{" or "}}". For more information, see [Implicit conversions](#implicit-conversions). -If the interpolated string contains other characters with special meaning in an interpolated string, such as the quotation mark ("), colon (:), or comma (,), they should be escaped if they occur in literal text, or they should be included in an expression delimited by parentheses if they are language elements included in an interpolated expression. The following example escapes quotation marks to include them in the result string: +If the interpolated string contains other characters with special meaning in an interpolated string, such as the quotation mark ("), colon (:), or comma (,), they should be escaped if they occur in literal text. Or, if they're language elements included in an interpolated expression, they should be included in an expression delimited by parentheses. The following example escapes quotation marks to include them in the result string: [!code-vb[interpolated-strings](../../../../../samples/snippets/visualbasic/programming-guide/language-features/strings/interpolated-strings4.vb)] -## Implicit Conversions +## Implicit conversions There are three implicit type conversions from an interpolated string: @@ -52,23 +52,21 @@ There are three implicit type conversions from an interpolated string: This is the final result of a string interpretation. All occurrences of double curly braces ("{{" and "}}") are converted to a single curly brace. -2. Conversion of an interpolated string to an variable that allows you create multiple result strings with culture-specific content from a single instance. This is useful for including such things as the correct numeric and date formats for individual cultures. All occurrences of double curly braces ("{{" and "}}") remain as double curly braces until you format the string by explicitly or implicitly calling the method. All contained interpolation expressions are converted to {0}, {1}, and so on. +2. Conversion of an interpolated string to an variable that allows you to create multiple result strings with culture-specific content from a single instance. This is useful for including such things as the correct numeric and date formats for individual cultures. All occurrences of double curly braces ("{{" and "}}") remain as double curly braces until you format the string by explicitly or implicitly calling the method. All contained interpolation expressions are converted to {0}, {1}, and so on. - The following example uses reflection to display the members as well as the field and property values of an variable that is created from an interpolated string. It also passes the variable to the method. + The following example uses reflection to display the members as well as the field and property values of an variable that's created from an interpolated string. It also passes the variable to the method. [!code-vb[interpolated-strings2](../../../../../samples/snippets/visualbasic/programming-guide/language-features/strings/interpolated-strings2.vb)] - Note that the interpolated string can be inspected only by using reflection. If it is passed to a string formatting method, such as , its format items are resolved and the result string returned. + Note that the interpolated string can be inspected only by using reflection. If it's passed to a string formatting method, such as , its format items are resolved and the result string returned. 3. Conversion of an interpolated string to a variable that represents a composite format string. Inspecting the composite format string and how it renders as a result string might, for example, help you protect against an injection attack if you were building a query. A also includes: - A overload that produces a result string for the . - - An method that produces a string for the . - - A method that produces a result string for a specified culture. - All occurrences of double curly braces ("{{" and "}}") remain as double curly braces until you format. All contained interpolation expressions are converted to {0}, {1}, and so on. + All occurrences of double curly braces ("{{" and "}}") remain as double curly braces until you format. All contained interpolation expressions are converted to {0}, {1}, and so on. [!code-vb[interpolated-strings3](../../../../../samples/snippets/visualbasic/programming-guide/language-features/strings/interpolated-strings3.vb)]