ms_learn_csharp/003_Basic_string_formatting/003_csharp.md

# Perform basic string formatting

## Introduction

As a software developer, you'll need to write C# code to combine and format
literal and variable data to create a new value. That value might be displayed,
saved to file, or sent across the network. Fortunately, C# provides many ways
to combine and format data.

Suppose you want to display the output of a command-line application you're
writing. You want to display values including literal text, text in variables,
numeric data, and textual data in other languages. How would you format it
correctly so that the user can understand what your application is
communicating to them?

In this module, you'll use character escape sequences to format literal
strings of text to include special characters including tabs and line feeds —
even characters from different languages like Kanji or Cyrillic script! You'll
learn how to concatenate two strings together and will use string
interpolation to create a literal string template with replaceable parts.

By the end of this module, you'll be able to control how your data is
displayed to end users of your applications.

### Learning objectives

In this module, you will:

- Create string data containing tabs, new lines, and other special
characters
- Create string data containing Unicode characters
- Combine string data into a new string value via concatenation
- Combine string data into a new string value via interpolation

#### Prerequisites

- Beginner level experience with a .NET editor
- Beginner level experience with displaying a message to a console using the
`Console.WriteLine()` and `Console.Write(String)` methods.
- Beginner level experience with data types, declaring, initializing, setting,
and retrieving values from variables.

---

## Exercise

### Combine strings using character escape sequences

Suppose you've been asked to create a mockup of a command-line tool that will
generate invoices in both English and Japanese. You don't have to build the
actual functionality that generates the invoices yet. You only need to provide
the command line interface to internal customers in the billing department for
their approval. Your manager asked you to make sure you add formatting to make
the current progress of the tool clear. Your manager also asked you to provide
instructions for the Japanese users on how to generate invoices in Japanese.

### Format literal strings in C#

In this exercise, you'll learn different techniques to display special
characters and add different types of formatting to the output.

#### Character escape sequences

An escape character sequence is an instruction to the runtime to insert a
special character that will affect the output of your string. In C#, the
escape character sequence begins with a backslash `\` followed by the character
you're escaping. For example, the `\n` sequence will add a new line, and a `\t`
sequence will add a tab.

The following code uses escape character sequences to add newlines and tabs:

```cs
Console.WriteLine("Hello\nWorld!");
Console.WriteLine("Hello\tWorld!");
```

If you run the code, you'll see the following output:

Output

```txt
Hello
World!
Hello   World!
```

What if you need to insert a double-quotation mark in a literal string? If you
don't use the character escape sequence, you'll confuse the compiler because
it will think you want to terminate the string prematurely. The compiler won't
understand the purpose of the characters after the second double-quotation mark.

```cs
Console.WriteLine("Hello "World"!");
```

The .NET Editor will put a red squiggly line under World. But if you attempt
to run the code anyway, you would see the following output:

```txt
(1,27): error CS1003: Syntax error, ',' expected
(1,27): error CS0103: The name 'World' does not exist in the current context
(1,32): error CS1003: Syntax error, ',' expected
```

To handle that situation, use the `\"` escape sequence:

```cs
Console.WriteLine("Hello \"World\"!");
```

If you run the code above, you would see the following output:

Output

```txt
Hello "World"!
```

What if you need to use the backslash for other purposes, like to display a
file path?

```cs
Console.WriteLine("c:\source\repos");
```

Unfortunately, C# reserves the backslash for escape sequences, so if you run
the code, the compiler will display the following error:

Output

```txt
(1,22): error CS1009: Unrecognized escape sequence
```

The problem is the sequence `\s`. The `\r` doesn't produce an error because it
's a valid escape sequence for a carriage return. However, you don't want to
use a carriage return in this context.

To solve this problem, you use the `\\` to display a single backslash.

```cs
Console.WriteLine("c:\\source\\repos");
```

Escaping the back slash character produces the output you intended:

Output

```txt
c:\source\repos
```

Format output using character escape sequences

To create the mockup of the command line tool, enter the following code in the
editor:

```cs
Console.WriteLine("Generating invoices for customer \"Contoso Corp\" ... \n");
Console.WriteLine("Invoice: 1021\t\tComplete!");
Console.WriteLine("Invoice: 1022\t\tComplete!");
Console.WriteLine("\nOutput Directory:\t");
```

Now, run the code. You'll see the following result in the output console:

Output

```txt
Generating invoices for customer "Contoso Corp" ...

Invoice: 1021           Complete!
Invoice: 1022           Complete!

Output Directory:    
```

### Verbatim string literal

A verbatim string literal will keep all whitespace and characters without the
need to escape the backslash. To create a verbatim string, use the `@` directive
before the literal string.

```cs
Console.WriteLine(@"    c:\source\repos    
        (this is where your code goes)");
```

Notice that the string spans two lines and the whitespace generated by this C#
instruction is kept in the following output.

Output

```txt
    c:\source\repos    
        (this is where your code goes)
```

#### Format output using verbatim string literals

Add the following line of code beneath the code that you created previously:

```cs
Console.Write(@"c:\invoices");
```

Now, run the code. You'll see the following result that includes the "Output
Directory":

Output

```txt
Generating invoices for customer "Contoso Corp" ...

Invoice: 1021           Complete!
Invoice: 1022           Complete!

Output Directory:
c:\invoices
```

### Unicode escape characters

You can also add encoded characters in literal strings using the `\u` escape
sequence, then a four-character code representing some character in Unicode 
(UTF-16).

```cs
// Kon'nichiwa World
Console.WriteLine("\u3053\u3093\u306B\u3061\u306F World!");
Console.WriteLine(@"c:\invoices\app.exe -j");
```

> Note  
> There are several caveats here. First, some consoles like the Windows
Command Prompt will not display all Unicode characters. It will replace those
characters with question mark characters instead. Also, the examples used here
are UTF-16. Some characters require UTF-32 and therefore require a different
escape sequence. This is a complicated subject, and this module is only aiming
at showing you what is possible. Depending on your need, you may need to spend
quite a bit of time learning and working with Unicode characters in your
applications.

#### Format output using unicode escape characters

To complete the mock-up of the command-line tool, you'll add a phrase in
Japanese that translates: "To generate Japanese invoices". Then you'll display
a verbatim literal string that represents a command the user can enter. You'll
also add some escape sequences for formatting.

Add the following code to your application:

```cs
// To generate Japanese invoices:
// Nihon no seikyū-sho o seisei suru ni wa:
Console.Write("\n\n\u65e5\u672c\u306e\u8acb\u6c42\u66f8\u3092\u751f\u6210\u3059\u308b\u306b\u306f\uff1a\n\t");
// User command to run an application
Console.WriteLine(@"c:\invoices\app.exe -j");
```

To ensure your code is correct, compare it with the following:

```cs
Console.WriteLine("Generating invoices for customer \"Contoso Corp\" ...\n");
Console.WriteLine("Invoice: 1021\t\tComplete!");
Console.WriteLine("Invoice: 1022\t\tComplete!");
Console.WriteLine("\nOutput Directory:\t");
Console.Write(@"c:\invoices");

// To generate Japanese invoices:
// Nihon no seikyū-sho o seisei suru ni wa:
Console.Write("\n\n\u65e5\u672c\u306e\u8acb\u6c42\u66f8\u3092\u751f\u6210\u3059\u308b\u306b\u306f\uff1a\n\t");
// User command to run an application
Console.WriteLine(@"c:\invoices\app.exe -j");
```

Now, run the code. You'll see the following result in the output console:

Output

```txt
Generating invoices for customer "Contoso Corp" ...

Invoice: 1021            Complete!
Invoice: 1022            Complete!

Output Directory:
c:\invoices

日本の請求書を生成するには：
    c:\invoices\app.exe -j
```

### Recap

Here's what you've learned about formatting literal strings so far:

- Use character escape sequences when you need to insert a special character
into a literal string, like a tab `\t`, new line `\n`, or a double quotation
mark `\"`.
- Use an escape character for the backslash `\\` when you need to use a
backslash in all other scenarios.
- Use the `@` directive to create a verbatim string literal that keeps all
whitespace formatting and backslash characters in a string.
- Use the `\u` plus a four-character code to represent Unicode characters
(UTF-16) in a string.
- Unicode characters may not print correctly depending on the application.

---

## Exercise

### Combine strings using string concatenation

Often, you'll need to combine data from many different sources, including
literal strings and variables containing both text and numeric data. In this
unit, you'll use string concatenation to combine two or more values into a new
string.

### What is string concatenation?

String concatenation is "programmer speak" for simply combining two or more
string values into a new string value. Unlike addition, the second value is
appended to the end of the first value, and so on. In the following exercise,
you'll write code to concatenate string values together.

#### Concatenate a literal string and a variable

To concatenate two strings together, you use the string concatenation operator,
which is the plus symbol `+`.

Enter the following code in the code editor:

```cs
string firstName = "Bob";
string message = "Hello " + firstName;
Console.WriteLine(message);
```

Now, run the code. You'll see the following result in the output console:

Output

```txt
Hello Bob
```

Notice the order—the first string `"Hello "` is first in the new string, and
the value in the `firstName` variable is appended to the end of it.

Concatenate multiple variables and literal strings
You can perform several concatenation operations in the same line of code.

Modify the code you wrote earlier to the following:

```cs
string firstName = "Bob";
string greeting = "Hello";
string message = greeting + " " + firstName + "!";
Console.WriteLine(message);
```

Here you create a more complex message by combining several variables and
literal strings.

Now, run the code. You'll see the following result in the output console:

```txt
Hello Bob!
```

#### Avoiding intermediate variables

In the previous steps, you used an extra variable to hold the new string that
resulted from the concatenation operation. Unless you have a good reason to do
so, you can (and should) avoid using intermediate variables by performing the
concatenation operation as you need it.

Modify the code you wrote earlier to the following:

```cs
string firstName = "Bob";
string greeting = "Hello";
Console.WriteLine(greeting + " " + firstName + "!");
```

Now, run the code. The result in the output console should be the same even if
you simplified the code:

```
Hello Bob!
```

### Recap

Here's what you've learned about string concatenation so far:

String concatenation allows you to combine smaller literal and variable
strings into a single string.
Avoid creating intermediate variables if adding them doesn't increase
readability.

---

## Exercise

### Combine strings using string interpolation

While string concatenation is simple and convenient, string interpolation is
growing in popularity in situations where you need to combine many literal
strings and variables into a single formatted message.

#### What is string interpolation?

String interpolation combines multiple values into a single literal string by
using a "template" and one or more interpolation expressions. An interpolation
expression is indicated by an opening and closing curly brace symbol `{ }`. You
can put any C# expression that returns a value inside the braces. The literal
string becomes a template when it's prefixed by the `$` character.

In other words, instead of writing the following line of code:

```cs
string message = greeting + " " + firstName + "!";
```

You can write this more concise line of code instead:

```cs
string message = $"{greeting} {firstName}!";
```

In this simple example, you save a few keystrokes. You can imagine how much
more concise string interpolation can be in more complex operations. Moreover,
many find the string interpolation syntax cleaner and easier to read.

In the following exercise, you'll rewrite the previous messages using string
interpolation.

#### Use string interpolation to combine a literal string and a variable value

To interpolate two strings together, you create a literal string and prefix
the string with the `$` symbol. The literal string should contain at least
one set of curly braces `{}` and inside of those characters you use the name
of a variable.

Enter the following code in the .NET Editor:

```cs
string firstName = "Bob";
string message = $"Hello {firstName}!";
Console.WriteLine(message);
```

Now, run the code. You'll see the following result in the output console:

Output

```txt
Hello Bob!
```

Use string interpolation with multiple variables and literal strings
You can perform several interpolation operations in the same line of code.

Modify the code you wrote earlier to the following:

```cs
int version = 11;
string updateText = "Update to Windows";
string message = $"{updateText} {version}";
Console.WriteLine(message);
```

Now, run the code. You'll see the following result in the output console:

Output

```
Update to Windows 11
```

#### Avoid intermediate variables

Just as you did in the previous exercise, you can eliminate the temporary
variable to store the message.

Modify the code you wrote earlier to the following:

```cs
int version = 11;
string updateText = "Update to Windows";
Console.WriteLine($"{updateText} {version}!");
```

Now, run the code. The result in the output console should be the same even if
you simplified the code:

Output

```txt
Update to Windows 11!
```

#### Combine verbatim literals and string interpolation

Suppose you need to use a verbatim literal in your template. You can use both
the verbatim literal prefix symbol `@` and the string interpolation `$` symbol
together.

```cs
string projectName = "First-Project";
Console.WriteLine($@"C:\Output\{projectName}\Data");
```

Now, run the code and you should see the following result.

Output

```txt
C:\Output\First-Project\Data
```

In this example, the $ symbol allows you to reference the projectName variable
inside the braces, while the `@` symbol allows you to use the unescaped `\`
character.

### Recap

Here's what you've learned about string interpolation so far:

- String interpolation provides an improvement over string concatenation by
reducing the number of characters required in some situations.
- You can combine string interpolation and verbatim literals by combining the
symbols for each and using that as a prefix for the string template.

---