3. The Basics of the C# Language

3.1. Introduction

We’ll start by treating C# as a traditional programming language. We’ll cover classes in the next chapter. In a program, there are two main components:

data;
the instructions that manipulate them.

We generally strive to separate data from instructions:

All the examples in this chapter are single-file applications: a single file, [.cs], without a project file ([.csproj]), which is run using the command [dotnet run basics-01.cs]. This feature, introduced with .NET 10, was covered in the previous chapter. The examples are located in the [03-basics] folder of the course code. They run in the French locale (fr-FR), as on a French Windows machine: real numbers are displayed with a decimal comma.

3.2. The Minimal Program

3.2.1. High-level instructions

The program [basics-01.cs] is as follows:

// minimal program written with top-level statements (C# 9)
// the statements are written directly in the file: no class, no Main method
Console.WriteLine("Hello world!");
// the full name of the Console class is System.Console
System.Console.WriteLine("Number of arguments received: " + args.Length);

Results:

1
2
3

> dotnet run basics-01.cs
Hello world!
Number of arguments received: 0

Comments:

The program contains neither classes nor methods: the statements are written directly in the file. These are called high-level statements (C# 9, 2020). A single program file can contain them;
Line 3: The [WriteLine] method of the [Console] class prints a line to the screen;
line 5: The class [Console] belongs to the namespace [System]. Its full name is [System.Console]. A namespace groups related types, just as a folder groups files;
line 5: the program has an array [args] containing the command-line arguments. We’ll come back to this in the “Main Program Arguments” section. The number of elements in the array is [args.Length]. The + operator concatenates a string and a number here: the number is first converted to a string.

With two command-line arguments (everything following [--] is passed to the program):

1
2
3

> dotnet run basics-01.cs -- a0 a1
Hello world!
Number of arguments received: 2

3.2.2. The classic form with a Main method

The 2008 course (C# 3.0) did not cover high-level instructions. The same program was written as follows: [basics-02.cs]:

// the classic form of the same program (the only one possible until C# 8)
using System;

namespace Basics
{
    class Program
    {
        // the Main method is the entry point of the program
        static void Main(string[] args)
        {
            Console.WriteLine("Hello world!");
            System.Console.WriteLine("Number of arguments received: " + args.Length);
        }
    }
}

Results:

1
2
3

> dotnet run basics-02.cs
Hello world!
Number of arguments received: 0

Comments:

line 2: the directive [using] imports the namespace [System]. You can then write [Console] instead of [System.Console];
Line 4: The class is placed in the [Basics] namespace. Starting with C# 10, you can write [namespace Basics;] (file-scope namespace): the entire file then belongs to this namespace, without curly braces or additional indentation. This is the form we will use from now on;
Line 6: In C#, all code belongs to a class. The class here is called [Program];
Line 9: The static method [Main] is the program’s entry point: this is the method the system executes upon launch. Its parameter, [args], receives the command-line arguments.

The two programs are equivalent. When it encounters high-level instructions, the compiler generates a class and a method named [Main] that contain these instructions, as well as the parameter [string[] args]. High-level instructions are therefore simply a shorthand form of the standard syntax. They are well-suited for the small programs in this chapter; the standard syntax remains useful when you want to inspect the class that contains [Main].

3.2.3. Implicit `using` statements

The program [basics-01.cs] uses the class [Console] without the [using System;] directive. This is possible because the .NET SDK automatically adds a generated file containing [global using] directives (C# 10) to every console program, which apply to all files in the program. For [basics-01.cs], this file contains:

// <auto-generated/>
global using System;
global using System.Collections.Generic;
global using System.IO;
global using System.Linq;
global using System.Net.Http;
global using System.Threading;
global using System.Threading.Tasks;

These are the implicit using statements: the most commonly used namespaces are imported automatically. A namespace not included in this list, such as [System.Globalization], must always be imported using a [using] directive at the top of the file. In the program [basics-02.cs], the directive [using System;] is therefore redundant: we left it in to show the 2008 format.

3.3. C# Data

C# uses the following data types:

integers;
real numbers;
decimal numbers;
characters and character strings;
Booleans;
objects.

3.3.1. Predefined data types

C# Type	Type .NET	Data represented	Literal suffix	Encoding	Value range
[char]	[Char] (S)	character		2 bytes	Unicode character (UTF-16)
[string]	[String] (C)	character string			reference to a Unicode character sequence
[int]	[Int32] (S)	integer		4 bytes	[-2³¹, 2³¹-1] or [-2147483648, 2147483647]
[uint]	[UInt32] (S)	unsigned integer	U	4 bytes	[0, 2³²-1] or [0, 4294967295]
[long]	[Int64] (S)	integer	L	8 bytes	[-2⁶³, 2⁶³-1] or [-9223372036854775808, 9223372036854775807]
[ulong]	[UInt64] (S)	unsigned integer	UL	8 bytes	[0, 2⁶⁴-1] or [0, 18446744073709551615]
[sbyte]	[SByte] (S)	integer		1 byte	[-2⁷, 2⁷-1] or [-128, 127]
[byte]	[Byte] (S)	unsigned integer		1 byte	[0, 2⁸-1] or [0, 255]
[short]	[Int16] (S)	integer		2 bytes	[-2¹⁵, 2¹⁵-1] or [-32768, 32767]
[ushort]	[UInt16] (S)	unsigned integer		2 bytes	[0, 2¹⁶-1] or [0, 65535]
[float]	[Single] (S)	real number	F	4 bytes	[1,5 10⁻⁴⁵, 3,4 10³⁸] in absolute value, 7 significant digits
[double]	[Double] (S)	real number	D	8 bytes	[5,0 10⁻³²⁴, 1,7 10³⁰⁸] in absolute value, 15 to 16 significant digits
[decimal]	[Decimal] (S)	decimal number	M	16 bytes	[1,0 10⁻²⁸, 7,9 10²⁸] as an absolute value, 28 to 29 significant digits
[bool]	[Boolean] (S)	Boolean		1 byte	[true], [false]
[object]	[Object] (C)	object reference			reference to an object of any type

Above, we have listed the equivalent .NET types for each C# type, marked with (S) if the type is a structure and (C) if it is a class. We see that there are two possible names for a 32-bit integer: [int] and [Int32]. The type [int] is a C# keyword. [Int32] is a structure belonging to the [System] namespace: its full name is [System.Int32]. The type [int] is a C# alias that refers to the structure .NET [System.Int32]. Similarly, the C# type [string] is an alias for the .NET [System.String] type. [System.String] is a class, not a structure. The two concepts are similar, but with the following fundamental difference:

a variable of type structure directly contains its value: this is called a value type;
a variable of a class type contains the address of the object (its reference); this is known as a reference type.

In addition, there are two less common types:

[nint] and [nuint] (C# 9) are signed and unsigned integers whose size is that of a memory address: 4 bytes on a 32-bit system, 8 bytes on a 64-bit system. They are primarily used to interact with native code;
[System.Half] (.NET 5) is a 2-byte, low-precision floating-point number used in graphics computing and machine learning. It is not a predefined language type: it does not have a C# keyword.

A structure, like a class, is a complex type with properties and methods. Thus, we can write:

string? typeName = 3.GetType().FullName;

The literal 3 is by default of type C# [int], and therefore of type .NET [System.Int32]. This structure has a method [GetType()] that returns an object describing the data type. Among the properties of this object, [FullName] is the full name of the type. The literal 3 is therefore a more complex object than it appears at first glance. The question mark in [string?] will be explained a little later.

The program [basics-03.cs] illustrates these various points:

// the predefined types: .NET type and size in bytes
int integer = 2;
float fl = 10.5F;
double d = -4.6;
string s = "test";
uint ui = 5;
long l = 1000;
ulong ul = 1001;
byte octet = 5;
sbyte so = -5;
short sh = -4;
ushort ush = 10;
decimal dec = 10.67M;
bool b = true;
char c = 'A';
// {0}, {1}, {2} are replaced by parameters no. 0, 1, 2 that follow the format
Console.WriteLine("Type of integer[{1}] : [{0},{2}]", integer.GetType().FullName, integer, sizeof(int));
Console.WriteLine("Type of fl[{1}] : [{0},{2}]", fl.GetType().FullName, fl, sizeof(float));
Console.WriteLine("Type of d[{1}] : [{0},{2}]", d.GetType().FullName, d, sizeof(double));
Console.WriteLine("Type of s[{1}] : [{0}]", s.GetType().FullName, s);
Console.WriteLine("Type of ui[{1}] : [{0},{2}]", ui.GetType().FullName, ui, sizeof(uint));
Console.WriteLine("Type of l[{1}] : [{0},{2}]", l.GetType().FullName, l, sizeof(long));
Console.WriteLine("Type of ul[{1}] : [{0},{2}]", ul.GetType().FullName, ul, sizeof(ulong));
Console.WriteLine("Type of octet[{1}] : [{0},{2}]", octet.GetType().FullName, octet, sizeof(byte));
Console.WriteLine("Type of so[{1}] : [{0},{2}]", so.GetType().FullName, so, sizeof(sbyte));
Console.WriteLine("Type of sh[{1}] : [{0},{2}]", sh.GetType().FullName, sh, sizeof(short));
Console.WriteLine("Type of ush[{1}] : [{0},{2}]", ush.GetType().FullName, ush, sizeof(ushort));
Console.WriteLine("Type of dec[{1}] : [{0},{2}]", dec.GetType().FullName, dec, sizeof(decimal));
Console.WriteLine("Type of b[{1}] : [{0},{2}]", b.GetType().FullName, b, sizeof(bool));
Console.WriteLine("Type of c[{1}] : [{0},{2}]", c.GetType().FullName, c, sizeof(char));
// integer whose size is that of a memory address (4 or 8 bytes depending on the machine)
nint ni = 7;
Console.WriteLine("Type of ni[{1}] : [{0},{2}]", ni.GetType().FullName, ni, nint.Size);
// 2-byte real number (.NET 5)
Half h = (Half)1.5;
Console.WriteLine("Type of h[{1}] : [{0}]", h.GetType().FullName, h);
// the literal 3 is also an object
Console.WriteLine("Type of the literal 3 : " + 3.GetType().FullName);
// extreme values
Console.WriteLine("int : [{0}, {1}]", int.MinValue, int.MaxValue);
Console.WriteLine("long : [{0}, {1}]", long.MinValue, long.MaxValue);
Console.WriteLine("decimal : [{0}, {1}]", decimal.MinValue, decimal.MaxValue);

Results:

> dotnet run basics-03.cs
Type of integer[2] : [System.Int32,4]
Type of fl[10,5] : [System.Single,4]
Type of d[-4,6] : [System.Double,8]
Type of s[test] : [System.String]
Type of ui[5] : [System.UInt32,4]
Type of l[1000] : [System.Int64,8]
Type of ul[1001] : [System.UInt64,8]
Type of octet[5] : [System.Byte,1]
Type of so[-5] : [System.SByte,1]
Type of sh[-4] : [System.Int16,2]
Type of ush[10] : [System.UInt16,2]
Type of dec[10,67] : [System.Decimal,16]
Type of b[True] : [System.Boolean,1]
Type of c[A] : [System.Char,2]
Type of ni[7] : [System.IntPtr,8]
Type of h[1,5] : [System.Half]
Type of the literal 3 : System.Int32
int : [-2147483648, 2147483647]
long : [-9223372036854775808, 9223372036854775807]
decimal : [-79228162514264337593543950335, 79228162514264337593543950335]

Comments:

line 2: declaration of an integer [integer] initialized to 2;
line 16: the statement [Console.WriteLine("... {0} ... {1} ...", param0, param1, ...)] displays the text specified as its first parameter (the format) on the screen, replacing each {i} with the value of the i-th parameter following the format. Parameters are numbered starting from 0;
line 17: the type of a variable [v] is obtained via [v.GetType().FullName]. The size in bytes of a predefined value type [T] is obtained via [sizeof(T)];
line 20: Since the type [string] refers to a class and not a structure, the operator [sizeof] cannot be used;
line 33: [sizeof(nint)] is not allowed in regular code because the size of [nint] is only known at runtime. The property [nint.Size] specifies that it is 8 bytes on the 64-bit machine being used;
line 35: You cannot write [Half h = 1.5;]: there is no implicit conversion from a [double] to a [Half]. The notation [(Half)] is an explicit conversion (known as a “cast” in English), which we will examine later;
lines 40–42: The properties [MinValue] and [MaxValue] of the numeric types specify the bounds of their value domains.

The output displays the type names .NET rather than the C# aliases. Note the decimal comma for floating-point numbers: the numbers are converted to strings according to the system’s locale, in this case French.

3.3.2. Notation for Literal Data

Data	Examples of literals
[int] integer (32 bits)	145, -7, 0xFF (hexadecimal), 0b1010_1010 (binary)
Integer [long] (64 bits), suffix L	100000L, 1_000_000_000_000L
unsigned integer, suffix U or UL	4000000000U, 10UL
floating-point [double]	134.789, -45E-18 (-45 × 10⁻¹⁸)
real [float], suffix F	134.789F, -45E-18F
real [decimal], suffix M	100000.50M
character [char]	'A', 'b', '\n', '\u00e9'
string [string]	"today", "c:\\chap1", @"c:\chap1", $"{name} is {age} years old", """plain text"""
boolean [bool]	[true], [false]
date	[new DateTime(1954, 10, 13)] (year, month, day) for 10/13/1954

In the source code, floating-point numbers are always written with a decimal point, regardless of the system’s locale. Since C# 7, integers can be written in binary (prefixed with [0b]) and groups of digits can be separated by the _ character to improve readability: [1_000_000] is the integer one million.

A standard string literal can contain escape sequences introduced by the \ character: "\n" represents the end-of-line character and not the sequence of the two characters \ and n, "\t" represents a tab, "\"" represents a double quote, and "\\" represents the \ character itself. To write the Windows path c:\chap1\paragraph3, you must therefore write "c:\\chap1\\paragraph3". You can also write @"c:\chap1\paragraph3": the @"text" syntax specifies that the text should be taken exactly as written, without interpreting the \ character. This is called a verbatim string.

C# now offers two other types of strings:

the interpolated string (C# 6) $"...": expressions enclosed in curly braces are evaluated, and their values are inserted into the string. An expression can be followed by a format specifier after the colon: [$"{d1:F2}"] displays the floating-point number [d1] with two decimal places. This is the most readable way to construct a string, and we will use it from now on instead of the {0}, {1}, ... formats;
The raw string (C# 11) """...""" : It begins and ends with at least three quotation marks. It can contain quotation marks and unescaped \ characters, and can span multiple lines. Spaces preceding the closing quotation marks are removed from each line, allowing the text to be indented with the code. This is very useful for writing JSON, SQL, or HTML.

The program [basics-04.cs] demonstrates these different notations:

// the notation of literal data
// integers: decimal, hexadecimal (0x), binary (0b), separator _
int i1 = 145, i2 = -7, i3 = 0xFF, i4 = 0b1010_1010;
long l1 = 100000L, l2 = 1_000_000_000_000L;
Console.WriteLine("integers : {0} {1} {2} {3} {4} {5}", i1, i2, i3, i4, l1, l2);
// real numbers
double d1 = 134.789, d2 = -45E-18;
float f1 = 134.789F;
decimal m1 = 100000.50M;
Console.WriteLine("reals : {0} {1} {2} {3}", d1, d2, f1, m1);
// characters and booleans
char c1 = 'A', c2 = '\u00e9';
bool b1 = true;
Console.WriteLine("characters : {0} {1}, boolean : {2}", c1, c2, b1);
// a date: (year, month, day)
DateTime birth = new DateTime(1954, 10, 13);
Console.WriteLine("date : {0}", birth.ToShortDateString());

// classic strings: the \ character introduces an escape sequence
string path1 = "c:\\chap1\\paragraph3";
// verbatim string: the text is taken as is
string path2 = @"c:\chap1\paragraph3";
Console.WriteLine(path1);
Console.WriteLine(path2);
Console.WriteLine("line 1\nline 2\t[tab]");

// interpolated string: the expressions between braces are evaluated
string name = "dupont";
int age = 23;
Console.WriteLine($"{name} is {age} years old, in 10 years he will be {age + 10}");
// with a format after the : character
Console.WriteLine($"d1={d1:F1}, i3 in hexadecimal={i3:X}, i4 in binary={i4:B8}, l2={l2:N0}");
Console.WriteLine($"date={birth:dddd d MMMM yyyy}");

// raw string (C# 11): no escaping, no doubling of quotes
string json = """
    {
      "name": "dupont",
      "path": "c:\chap1"
    }
    """;
Console.WriteLine(json);
// interpolated raw string: with $$, the expressions are between {{ and }}
string json2 = $$"""{ "name": "{{name}}", "age": {{age}} }""";
Console.WriteLine(json2);

Results:

> dotnet run basics-04.cs
integers : 145 -7 255 170 100000 1000000000000
reals : 134,789 -4,5E-17 134,789 100000,50
characters : A é, boolean : True
date : 13/10/1954
c:\chap1\paragraph3
c:\chap1\paragraph3
line 1
line 2    [tab]
dupont is 23 years old, in 10 years he will be 33
d1=134,8, i3 in hexadecimal=FF, i4 in binary=10101010, l2=1 000 000 000 000
date=mercredi 13 octobre 1954
{
  "name": "dupont",
  "path": "c:\chap1"
}
{ "name": "dupont", "age": 23 }

Comments:

line 3: [0xFF] is 255 and [0b1010_1010] is 170;
line 7: -45E-18 is displayed as -4,5E-17: this is the same value, normalized;
line 12: the sequence \u00e9 denotes the Unicode character with hexadecimal code 00E9, i.e., é;
line 16: a date. The method [ToShortDateString] displays it in the short format used in French culture. For a date without a time, .NET 6 added the type [DateOnly]; we’ll revisit this in Chapter 5;
lines 20–22: the two strings are identical, as shown in the output;
line 30: an interpolated string. The expressions [name], [age], and [age + 10] are evaluated and then inserted into the string;
line 32: a few formats: F1 (one decimal place), X (hexadecimal), B8 (8-digit binary, .NET 8), N0 (thousands separator, no decimal place);
line 33: a custom date format: day of the week, day, month in words, year;
lines 36–41: a multi-line raw string. Quotation marks and the \ character are written as-is. The four spaces preceding the closing quotation marks have been removed from each line;
line 44: an interpolated raw string. With two $ characters, expressions are written between double curly braces {{ and }}: the single curly braces, which appear frequently in JSON, remain plain text.

3.3.3. Data Declaration

3.3.3.1. Role of declarations

A program manipulates data characterized by a name and a type. This data is stored in memory. When the program is compiled, the compiler assigns each piece of data a memory location characterized by an address and a size. It does this based on the declarations made by the programmer. Furthermore, these declarations allow the compiler to detect programming errors. Thus, the operation [x = x * 2;] will be declared invalid if [x] is a character string.

3.3.3.2. Declaring Constants

The syntax for declaring a constant is as follows:

const type name = value;

For example:

const double VatRate = 0.2;

Why declare constants?

The program is easier to read if the constant is given a meaningful name;
it is easier to modify the program if the “constant” needs to be changed. Thus, if the VAT rate changes to 0.25, the only modification needed will be to the statement that defines its value: [const double VatRate = 0.25;]. If 0.2 had been used explicitly in the program, numerous statements would need to be modified.

The value of a constant must be known at compile time: a number, a string, a Boolean, or an expression that can be calculated from other constants. By convention, in .NET, constant names begin with a capital letter.

3.3.3.3. Variable Declaration

A variable is identified by a name and is associated with a data type. C# distinguishes between uppercase and lowercase letters: the variables [END] and [end] are different.

Variables can be initialized when they are declared. The syntax for declaring one or more variables is:

type variable1 = value1, variable2 = value2, ...;

where [type] is a predefined type or a type defined by the programmer. Initialization is optional; however, C# does not allow the use of a local variable that has not yet been assigned a value.

You can also omit the type of a variable by using the keyword [var] in place of the type:

var variable1 = value1;

The keyword [var] does not mean that the variable has no specific type: it has the type of the value assigned to it, as determined by the compiler. Initialization is required here so that the compiler can deduce the type. We use [var] when the type is obvious from the value.

The program [basics-05.cs] is as follows:

// constants and variables
const double VatRate = 0.2;
const string Currency = "euros";
double priceExclTax = 100;
Console.WriteLine($"Price incl. tax : {priceExclTax * (1 + VatRate)} {Currency}");

// an explicitly typed piece of data
int i = 2;
Console.WriteLine($"Type of int i=2 : {i.GetType().Name},{i.GetType().FullName}");
// implicitly typed data with var
var j = 3;
Console.WriteLine($"Type of var j=3 : {j.GetType().Name},{j.GetType().FullName}");
var today = DateTime.Now;
Console.WriteLine($"Type of var today : {today.GetType().Name},{today.GetType().FullName}");
var x = 3.5;
var y = 3.5F;
var z = 10L;
var name = "dupont";
Console.WriteLine($"x : {x.GetType().Name}, y : {y.GetType().Name}, z : {z.GetType().Name}, name : {name.GetType().Name}");
// several variables declared on the same line
int a = 1, b, c = 3;
b = a + c;
Console.WriteLine($"a={a}, b={b}, c={c}");

Results:

> dotnet run basics-05.cs
Price incl. tax : 120 euros
Type of int i=2 : Int32,System.Int32
Type of var j=3 : Int32,System.Int32
Type of var today : DateTime,System.DateTime
x : Double, y : Single, z : Int64, name : String
a=1, b=4, c=3

Comments:

lines 2–3: two constants;
line 8: one explicitly typed data item;
line 9: [GetType().Name] is the short name of the type, [GetType().FullName] is its full name;
Line 11: an implicitly typed value. Because 3 is of type [int], [j] will be of type [int];
line 13: Because [DateTime.Now] (the current date and time) is of type [DateTime], [today] will be of type [DateTime];
lines 15–18: the inferred type depends on how the literal is written: 3.5 is a [double], 3.5F is a [float], and 10L is a [long];
Line 21: three variables declared on the same line; only [a] and [c] are initialized. [b] is assigned a value on the next line.

A variable implicitly typed by the keyword [var] cannot change its type afterward. Thus, after line 13, you could not write:

1	`today = "today";`

because [today] is of type [DateTime]. We will see in Chapter 5, with LINQ, that it is possible to create a type “on the fly” within an expression: this is an anonymous type, to which the programmer has not assigned a name. If data of an anonymous type is to be assigned to a variable, the only way to declare that variable is to use the keyword [var].

3.3.4. Nullable Types

A variable of a value type, such as [int], always contains a value. It is sometimes useful to be able to express the absence of a value: an unknown age, an empty field in a database. The type [int?] (C# 2) is the type [int] with the value [null] added to it, which means “no value.” This is referred to as a nullable value type. The principle applies to all value types: [double?], [bool?], [DateTime?], ...

A variable of a reference type, such as [string], can always have the value [null]: this means that it does not reference any object. Attempting to use a member of such a variable—for example, its property [Length]—will result in a runtime error ([NullReferenceException]), one of the most common errors in C#. Starting with C# 8, the compiler can help prevent this: with nullable reference types—enabled by default in projects created using the [dotnet new] command and in single-file applications—

the type [string] denotes a string that never evaluates to [null];
the type [string?] refers to a string that can be [null].

The compiler tracks the possible values of variables and issues a warning when there is a risk of using the value [null]: assigning [null] to a variable [string], using [Length] on a variable [string?] that has not been tested, etc. Unlike [int?], [string?] does not create a new type at runtime: it is a directive intended for the compiler.

We’ll encounter these types right from the first examples, because the method [Console.ReadLine()], which reads a line typed on the keyboard, returns a [string?]: it returns [null] when there is nothing left to read (end of the input stream). The program [basics-06.cs] is as follows:

// nullable types
// a nullable value type (int?) accepts the null value in addition to integers
int? age = null;
Console.WriteLine($"age.HasValue={age.HasValue}");
age = 23;
Console.WriteLine($"age.HasValue={age.HasValue}, age.Value={age.Value}");
// int? -> int: an explicit conversion is needed (exception if age is null)
int n = (int)age;
Console.WriteLine($"n={n}");

// a nullable reference type (string?) accepts the null value
string? firstName = null;
Console.WriteLine($"firstName is null : {firstName == null}");
// the string type (without ?) is assumed never to be null
string name = "dupont";
Console.WriteLine($"name has {name.Length} characters");

// Console.ReadLine returns a string?: null if the input stream is exhausted
Console.Write("Type a line: ");
string? line = Console.ReadLine();
if (line == null)
{
    Console.WriteLine();
    Console.WriteLine("No line: the input stream is closed");
}
else
{
    // here the compiler knows that line is not null
    Console.WriteLine($"You typed [{line}] : {line.Length} character(s)");
}

Results when entering text via the keyboard:

> dotnet run basics-06.cs
age.HasValue=False
age.HasValue=True, age.Value=23
n=23
firstName is null : True
name has 6 characters
Type a line: hello
You typed [hello] : 5 character(s)

Results when the user presses Ctrl-D (Ctrl-Z followed by Enter on Windows), which closes the input stream:

> dotnet run basics-06.cs
age.HasValue=False
age.HasValue=True, age.Value=23
n=23
firstName is null : True
name has 6 characters
Type a line: 
No line: the input stream is closed

Comments:

line 3: [age] does not contain a value;
line 4: the [HasValue] property indicates whether the variable contains a value; the [Value] property provides that value;
line 8: a [int?] cannot be directly assigned to a [int] since it may be equal to [null]. An explicit conversion is required, which throws an exception if [age] is equal to [null]. We will discuss the safer [??] operator later;
line 12: a string that may be equal to [null];
line 15: a string that never equals [null]. Writing [name = null;] would trigger a compiler warning;
line 20: [Console.ReadLine()] evaluates to [string?]. Declaring [line] as type [string] would trigger a warning;
line 21: the value [null] is checked;
line 29: in the [else] branch, the compiler knows that [line] is not equal to [null]: it issues no warning for the use of [line.Length].

3.3.5. Conversions between numbers and strings

Conversion	Method
number -> string	[number.ToString()] or an interpolated string [$"{number}"]
string -> int	[int.Parse(str)] or [int.TryParse(str, out int number)]
string -> long	[long.Parse(str)] or [long.TryParse(str, out long number)]
string -> double	[double.Parse(str)] or [double.TryParse(str, out double number)]
string -> float	[float.Parse(str)] or [float.TryParse(str, out float number)]
string -> decimal	[decimal.Parse(str)] or [decimal.TryParse(str, out decimal number)]

Converting a string to a number may fail if the string does not represent a valid number. The [Parse] method then generates a fatal error called an exception. This error can be handled by the following [try / catch] clause:

try
{
    call the function likely to throw the exception
}
catch (Exception e)
{
    handle the exception e
}
next statement

If the function does not throw an exception, execution proceeds to the next statement; otherwise, it proceeds to the body of the [catch] clause, then to the next statement. We will revisit exception handling in the section dedicated to it.

The [TryParse] method (.NET 2.0) avoids the exception: it returns the boolean [true] if the conversion succeeds, [false] otherwise, and stores the resulting number in a variable passed using the keyword [out]. Starting with C# 7, this variable can be declared within the call itself: [int.TryParse(str, out var number)]. The [out] passing mode will be explained in the section on parameter passing. When incorrect input is expected—for example, from a keyboard—[TryParse] is preferable to [Parse]: an input error is not an exceptional situation.

The program [basics-07.cs] demonstrates several techniques for converting between numbers and character strings. The function [Display] displays the value of its parameter on the screen:

// conversions between numbers and character strings
using System.Globalization;

// data
const int i = 10;
const long l = 100000;
const float f = 45.78F;
double d = -14.98;

// number --> string
Display(i.ToString());
Display(l.ToString());
Display(f.ToString());
Display(d.ToString());

// boolean --> string
const bool b = false;
Display(b.ToString());

// string --> int
int i1 = int.Parse("10");
Display(i1.ToString());
try
{
    i1 = int.Parse("10.67");
    Display(i1.ToString());
}
catch (Exception e)
{
    Display("Error : " + e.Message);
}

// string --> long
long l1 = long.Parse("100");
Display(l1.ToString());
try
{
    l1 = long.Parse("10.675");
    Display(l1.ToString());
}
catch (Exception e)
{
    Display("Error : " + e.Message);
}

// string --> double
double d1 = double.Parse("100,87");
Display(d1.ToString());
try
{
    d1 = double.Parse("abcd");
    Display(d1.ToString());
}
catch (Exception e)
{
    Display("Error : " + e.Message);
}

// string --> float
float f1 = float.Parse("100,87");
Display(f1.ToString());
try
{
    f1 = float.Parse("abcd");
    Display(f1.ToString());
}
catch (Exception e)
{
    Display("Error : " + e.Message);
}

// TryParse: returns false instead of throwing an exception
if (int.TryParse("123", out int i2))
{
    Display($"TryParse(\"123\") succeeded : {i2}");
}
if (!int.TryParse("12x", out var i3))
{
    Display($"TryParse(\"12x\") failed, i3={i3}");
}

// the culture: decimal separator of the current culture
Display($"Current culture : {CultureInfo.CurrentCulture.Name}");
try
{
    d1 = double.Parse("100.87");
    Display(d1.ToString());
}
catch (FormatException e)
{
    Display("Error : " + e.Message);
}
// the invariant culture uses the decimal point
double d2 = double.Parse("100.87", CultureInfo.InvariantCulture);
Display(d2.ToString());
Display(d2.ToString(CultureInfo.InvariantCulture));
if (double.TryParse("3.14", CultureInfo.InvariantCulture, out double pi))
{
    Display($"pi={pi}");
}

// a local function (see later) that displays its parameter
static void Display(string s)
{
    Console.WriteLine($"S={s}");
}

Results:

> dotnet run basics-07.cs
S=10
S=100000
S=45,78
S=-14,98
S=False
S=10
S=Error : The input string '10.67' was not in a correct format.
S=100
S=Error : The input string '10.675' was not in a correct format.
S=100,87
S=Error : The input string 'abcd' was not in a correct format.
S=100,87
S=Error : The input string 'abcd' was not in a correct format.
S=TryParse("123") succeeded : 123
S=TryParse("12x") failed, i3=0
S=Current culture : fr-FR
S=Error : The input string '100.87' was not in a correct format.
S=100,87
S=100.87
S=pi=3,14

Comments:

line 2: the [System.Globalization] namespace, which contains the [CultureInfo] class, is not included in the implicit using statements;
Lines 5–8: the data to be converted;
lines 11–14: every object has a method [ToString()] that converts it to a string;
lines 25–30: the exception that [int.Parse] may throw is handled. [e.Message] is the error message associated with the [e] exception. The .NET exception messages are in English: .NET 10 does not provide a French translation;
line 47: the string uses a decimal comma, in accordance with the system’s French locale;
line 73: [TryParse] succeeds and stores 123 in the variable [i2], declared in the call;
line 77: [TryParse] fails and returns [false]; the variable [i3] is then assigned the value 0;
line 83: the program’s current locale is fr-FR;
line 86: In the French locale, the period is not a decimal separator: the conversion fails;
line 94: the invariant locale [CultureInfo.InvariantCulture] uses the decimal point, regardless of the machine. It is used to read and write numbers in files or in exchanges between programs, which must not depend on the user’s language;
lines 95–96: the same number converted to a string according to the current locale (100,87) and according to the invariant locale (100.87);
line 97: [TryParse] also accepts a locale;
lines 103–105: a local function. In a high-level programming language, you cannot write methods, since there are no classes; instead, you write local functions, which can be called before they are defined. They are discussed in the section “Local Functions and Tuples.”

The 2008 course stated that real numbers in string form must use a comma: this is true only in the French culture. A program that reads numbers must always know in which culture they were written.

3.3.6. Data Arrays

A C# array is an object that allows data of the same type to be grouped under a single identifier. It is declared as follows:

Type[] array = new Type[n];

[n] is the number of data elements the array can contain. The syntax [array[i]] refers to data element number i, where i belongs to the range [0, n-1]. Any reference to data item [array[i]] where i is not in the range [0, n-1] causes an exception. Upon creation, each element of the array is assigned the default value for its type: 0 for numbers, [false] for booleans, and [null] for reference types. An array can be initialized at the same time it is declared:

int[] integers = new int[] { 0, 10, 20, 30 };

or, more simply:

1	`int[] integers = { 0, 10, 20, 30 };`

or, starting with C# 12, using a collection expression:

1	`int[] integers = [0, 10, 20, 30];`

We will use this last form from now on. Arrays have a property [Length], which represents the number of elements they contain.

A two-dimensional array is declared as follows:

Type[,] array = new Type[n, m];

where [n] is the number of rows and [m] is the number of columns. The syntax [array[i, j]] refers to element j in row i. The two-dimensional array can also be initialized at the same time it is declared:

1	`double[,] reals = { { 0.5, 1.7 }, { 8.4, -6 } };`

The number of elements in each dimension is obtained using the method [GetLength(i)], where i=0 represents the dimension corresponding to the first index, i=1 represents the dimension corresponding to the second index, and so on. The number of dimensions is obtained using the property [Rank], and the total number of elements using the property [Length].

An array of arrays (also known as a staircase array) is declared as follows:

Type[][] array = new Type[n][];

The declaration above creates an array of n elements. Each element, [array[i]], is a one-dimensional array reference. These references are not initialized by the declaration above; they have the value [null]. Unlike a two-dimensional array, each row can have a different length.

C# 8 introduced two convenient notations:

backward indexing: [array[^1]] is the last element, [array[^2]] is the second-to-last, and so on. [array[^1]] is equivalent to [array[array.Length - 1]];
the range: [array[1..3]] is a new array consisting of the elements with indices 1 and 2. The start index is included, and the end index is excluded. The bounds can be omitted: [array[2..]] ranges from index 2 to the end, and [array[..^1]] ranges from the beginning to the second-to-last element, inclusive.

The program [basics-08.cs] combines these different arrays:

// arrays
// an initialized 1-dimensional array
int[] integers = new int[] { 0, 10, 20, 30 };
for (int i = 0; i < integers.Length; i++)
{
    Console.WriteLine($"integers[{i}]={integers[i]}");
}

// an initialized 2-dimensional array
double[,] reals = { { 0.5, 1.7 }, { 8.4, -6 } };
for (int i = 0; i < reals.GetLength(0); i++)
{
    for (int j = 0; j < reals.GetLength(1); j++)
    {
        Console.WriteLine($"reals[{i},{j}]={reals[i, j]}");
    }
}
Console.WriteLine($"reals : Rank={reals.Rank}, Length={reals.Length}");

// an array of arrays (jagged array)
string[][] names = new string[3][];
for (int i = 0; i < names.Length; i++)
{
    names[i] = new string[i + 1];
}
// initialization
for (int i = 0; i < names.Length; i++)
{
    for (int j = 0; j < names[i].Length; j++)
    {
        names[i][j] = "name" + i + j;
    }
}
// display
for (int i = 0; i < names.Length; i++)
{
    for (int j = 0; j < names[i].Length; j++)
    {
        Console.WriteLine($"names[{i}][{j}]={names[i][j]}");
    }
}

// an array created without initial values: elements at the default value of the type
bool[] flags = new bool[3];
string?[] strings = new string?[2];
Console.WriteLine($"flags[0]={flags[0]}, strings[0] is null : {strings[0] == null}");

// collection expression (C# 12)
int[] values = [0, 10, 20, 30, 40];
// string.Join joins the elements of an array with a separator
Console.WriteLine($"values=[{string.Join(", ", values)}]");
// index from the end (C# 8): ^1 denotes the last element
Console.WriteLine($"values[^1]={values[^1]}, values[^2]={values[^2]}");
// range (C# 8): the elements at indices 1 and 2 (the end bound is excluded)
int[] slice = values[1..3];
Console.WriteLine($"values[1..3]=[{string.Join(", ", slice)}]");
Console.WriteLine($"values[2..]=[{string.Join(", ", values[2..])}]");
Console.WriteLine($"values[..^1]=[{string.Join(", ", values[..^1])}]");
// the slice is a copy: the original array is not modified
slice[0] = 100;
Console.WriteLine($"slice[0]={slice[0]}, values[1]={values[1]}");

Results:

> dotnet run basics-08.cs
integers[0]=0
integers[1]=10
integers[2]=20
integers[3]=30
reals[0,0]=0,5
reals[0,1]=1,7
reals[1,0]=8,4
reals[1,1]=-6
reals : Rank=2, Length=4
names[0][0]=name00
names[1][0]=name10
names[1][1]=name11
names[2][0]=name20
names[2][1]=name21
names[2][2]=name22
flags[0]=False, strings[0] is null : True
values=[0, 10, 20, 30, 40]
values[^1]=40, values[^2]=30
values[1..3]=[10, 20]
values[2..]=[20, 30, 40]
values[..^1]=[0, 10, 20, 30]
slice[0]=100, values[1]=10

Comments:

line 3: a one-dimensional array is initialized;
line 4: a loop [for] iterates over indices from 0 to [integers.Length - 1]. The loop [for] is shown below;
line 10: a two-dimensional array (2 rows, 2 columns);
lines 11–13: [GetLength(0)] is the number of rows, [GetLength(1)] is the number of columns;
line 21: an array [names] with 3 elements. Each element is a reference to an array of type [string[]], currently [null];
line 24: the 3 elements of the array [names] are initialized. [names[i]] now references an array of i+1 strings;
line 31: [names[i][j]] is the jth element of the array referenced by [names[i]]. Since [names[i]] is an array, [names[i].Length] is the number of its elements. The expression “name” + i + j is evaluated from left to right: “name” + i yields a string, to which j is concatenated;
lines 44–45: arrays created without initial values. The type [string?[]] is an array whose elements can be [null];
line 49: a collection expression;
line 51: the method [string.Join] constructs a string using the array’s elements, separated by the string passed as the first parameter;
line 53: the last and second-to-last elements;
line 55: the elements at indices 1 and 2;
lines 60–61: a range creates a copy: modifying [slice] does not modify [values].

3.4. Basic C# Statements

There are:

basic statements executed by the computer;
instructions that control the flow of the program.

Basic instructions become clear when considering the structure of a microcomputer and its peripherals:

1: reading information from the keyboard;
2: processing information;
3: writing information to the screen.

3.4.1. Writing to the Screen

There are various instructions for writing to the screen:

Console.Out.WriteLine(expression);
Console.WriteLine(expression);
Console.Error.WriteLine(expression);

where [expression] is any data that can be converted to a character string for display on the screen. All C# or .NET objects have a [ToString()] method that is used to perform this conversion. The [Write] method does the same thing as [WriteLine] without wrapping to the next line.

Class [System.Console] provides access to screen-writing operations ([Write], [WriteLine]). It has two properties, [Out] and [Error], which are write streams of type [TextWriter]:

[Console.WriteLine()] is equivalent to [Console.Out.WriteLine()] and writes to the stream [Out], which is usually associated with the screen;
[Console.Error.WriteLine()] writes to the [Error] stream, which is also usually associated with the screen.

The streams [Out] and [Error] can be redirected to files at runtime, as we will see shortly.

3.4.2. Reading Data Entered via the Keyboard

The data stream from the keyboard is represented by the object [Console.In] of type [TextReader]. This object type allows you to read a line of text using the [ReadLine] method:

string? line = Console.In.ReadLine();

The [Console] class provides a method, [ReadLine], which is associated by default with the [In] stream. Therefore, you can write:

string? line = Console.ReadLine();

The line typed on the keyboard, without the end-of-line character, is stored in the variable [line] and can then be processed by the program. As we have seen, [ReadLine] returns [null] when the input stream is exhausted: this is why the variable is of type [string?]. The stream [In] can be redirected to a file, just like the streams [Out] and [Error].

3.4.3. Example of Input/Output

The program [basics-09.cs] illustrates keyboard/screen input and output operations:

// keyboard / screen input-output

// writing to the Out stream
object obj = new object();
Console.Out.WriteLine(obj);

// writing to the Error stream
int i = 10;
Console.Error.WriteLine("i=" + i);
Console.Error.WriteLine("i={0}", i);

// reading a line typed on the keyboard
Console.Write("Type a line: ");
string? line = Console.ReadLine();
Console.WriteLine($"line={line}");

Results:

> dotnet run basics-09.cs
System.Object
i=10
i=10
Type a line: here I am
line=here I am

Comments:

Line 4: [obj] is an object reference;
Line 5: [obj] is displayed on the screen. The method [obj.ToString()] is called to retrieve the text to be displayed;
line 9: the text is written to the [Error] stream;
line 10: the same thing, but with a format. The first parameter, "i={0}", is the display format; the other parameters are the expressions to be displayed. The {n} elements are positional parameters: at runtime, {n} is replaced by the value of the nth expression;
lines 13–14: a prompt is displayed without a line break, then the line typed on the keyboard is read;
line 15: in an interpolated string, a value like [null] would produce an empty string: no warning is issued.

In the results:

line 2: the output generated by line 5 of the code. The method *[obj.ToString()] displayed the type name of the variable *[obj]*: *[System.Object]*. The type [object] is a C# alias for the type .NET [System.Object]*;
Lines 3–4: The two entries for the [Error] stream appear on the screen as those for the [Out] stream.

3.4.4. Input/Output Redirection

Windows, Linux, and macOS recognize three standard devices:

the standard input device, which by default refers to the keyboard and is numbered 0;
the standard output device, which by default refers to the screen and is numbered 1;
the standard error device, which is set to the screen by default and is numbered 2.

In C#, the write stream [Console.Out] writes to device 1, the write stream [Console.Error] writes to device 2, and the read stream [Console.In] reads data from device 0.

When you run a program in a command window, you can specify which devices will be 0, 1, and 2 for the program being executed. After the program arguments, you can redirect the standard input and output devices to files:

Redirection	Meaning
0<in.txt or <in.txt	Standard input stream No. 0 is redirected to the file in.txt. In the program, the stream [Console.In] will therefore read its data from the file in.txt
1>out.txt or >out.txt	redirects output #1 to the file out.txt. In the program, the stream [Console.Out] will therefore write its data to the file out.txt
1>>out.txt or >>out.txt	Same as above, but the written data is appended to the current contents of the out.txt file
2>err.txt	redirects output #2 to the file err.txt. In the program, the stream [Console.Error] will therefore write its data to the file err.txt
2>>err.txt	Same as above, but the written data is appended to the current contents of the file err.txt
1>out.txt 2>err.txt	Devices 1 and 2 are both redirected to files

Note that to redirect a program’s input/output streams to files, the program does not need to be modified: the operating system determines the nature of devices 0, 1, and 2. Consider the following program, [basics-10.cs]:

// redirections of the input-output streams
// reading the In stream
string? data = Console.In.ReadLine();
// writing to the Out stream
Console.Out.WriteLine("writing to the Out stream : " + data);
// writing to the Error stream
Console.Error.WriteLine("writing to the Error stream : " + data);

The 2008 course generated an executable using Visual Studio and then ran it in a DOS window. Today, the command [dotnet run] is sufficient: the redirects are applied to the launched program. Here is a session in a Linux terminal (bash):

> echo test > in.txt
> cat in.txt
test
> dotnet run basics-10.cs < in.txt > out.txt 2> err.txt
> cat out.txt
writing to the Out stream : test
> cat err.txt
writing to the Error stream : test
> dotnet run basics-10.cs < in.txt 2> err.txt
writing to the Out stream : test
> dotnet run basics-10.cs < in.txt > out.txt
writing to the Error stream : test

Comments:

line 1: the string "test" is placed in the file in.txt;
line 2: display the contents of the file in.txt for verification;
line 4: run the program. The stream [In] is redirected to the file in.txt, the stream [Out] to the file out.txt, and the stream [Error] to the file err.txt. The execution does not result in any output;
lines 5–6: The contents of the file out.txt show that the file in.txt was read and that writing to the stream [Out] was redirected to out.txt;
lines 7–8: similar verification for the file err.txt;
lines 9–10: only the [Error] stream is redirected: the screen displays only the write operation to the [Out] stream;
lines 11–12: only the [Out] stream is redirected: the screen displays only the write operation on the [Error] stream.

It is clear that the streams [Out] and [Error] do not write to the same devices, since they could be redirected separately. The [Error] stream is intended for error messages: this allows you to redirect a program’s output to a file while still seeing its error messages on the screen.

The operators >, >>, and 2> are written the same way in the Windows command prompt ([cmd]), in PowerShell, and in bash. The < operator is recognized by [cmd] and bash, but not by PowerShell, which reserves it for future use: in PowerShell, it is used to send a file to a program’s standard input via a pipe (|). The following commands, provided for illustrative purposes (they were not executed for this course), do on Windows what the bash session above does:

rem Windows command prompt (cmd)
echo test>in.txt
dotnet run basics-10.cs <in.txt >out.txt 2>err.txt
type out.txt
type err.txt

# PowerShell
"test" > in.txt
Get-Content in.txt | dotnet run basics-10.cs > out.txt 2> err.txt
Get-Content out.txt
Get-Content err.txt

3.4.5. Assigning the value of an expression to a variable

Here we are interested in the operation [variable = expression;]. The expression can be arithmetic, relational, Boolean, string, etc.

3.4.5.1. Interpretation of the assignment operation

The operation [variable = expression;] is itself an expression that is evaluated as follows:

the right-hand side of the assignment is evaluated: the result is a value V;
the value V is assigned to the variable;
the value V is also the value of the assignment, now viewed as an expression.

Thus, the operation [V1 = V2 = expression] is valid. Since the = operator is evaluated from right to left, we get [V1 = (V2 = expression)]. The expression [V2 = expression] is evaluated and has the value V. Its evaluation caused V to be assigned to V2. The next = operator is then evaluated as [V1 = V]. The value of this expression is still V; its evaluation causes V to be assigned to V1. Thus, the operation [V1 = V2 = expression] is an expression whose evaluation:

causes the value of [expression] to be assigned to the variables V1 and V2;
returns the value of [expression].

This can be generalized to an expression of the form [V1 = V2 = ... = Vn = expression].

3.4.5.2. Arithmetic Expressions

The operators used in arithmetic expressions are as follows:

Operator	Role
+	addition
-	subtraction
*	multiplication
/	division: the result is the exact quotient if at least one of the operands is a real number. If both operands are integers, the result is the integer quotient. Thus, 5/2 equals 2 and 5.0/2 equals 2.5
%	remainder of division (modulo), regardless of the nature of the operands. The remainder has the same sign as the dividend: -5 % 2 equals -1

There are various mathematical functions. Here are a few:

Function	Role
[double Sqrt(double x)]	square root
[double Cos(double x)], [Sin], [Tan]	cosine, sine, tangent (angle in radians)
[double Pow(double x, double y)]	x to the power of y
[double Exp(double x)]	exponential
[double Log(double x)], [Log10], [Log2]	natural logarithm, decimal logarithm, base-2 logarithm
[Abs(x)], [Max(x, y)], [Min(x, y)]	absolute value, maximum, minimum (for all numeric types)
[Floor(x)], [Ceiling(x)], [Truncate(x)]	lower integer part, upper integer part, truncation
[Round(x)], [Round(x, n)]	rounding to the nearest integer, to n decimal places
[Math.PI], [Math.E]	the constants π and e

All these functions are defined in a .NET class named Math. When using them, you must prefix them with the name of the class in which they are defined. Thus, you would write:

double x, y = 4;
x = Math.Sqrt(y);

The 2008 course included the complete definition of the [Math] class here: Today, it can be found in the online documentation for .NET, learn.microsoft.com/dotnet/api/system.math.

The [basics-11.cs] program is as follows:

// arithmetic expressions
// integer division and real division
Console.WriteLine($"5 / 2 = {5 / 2}, 5.0 / 2 = {5.0 / 2}, 5 / 2.0 = {5 / 2.0}");
// remainder of the division (modulo)
Console.WriteLine($"5 % 2 = {5 % 2}, -5 % 2 = {-5 % 2}, 5.5 % 2 = {5.5 % 2}");
// real division by zero: no error, infinity or NaN (Not a Number)
double zero = 0;
Console.WriteLine($"1 / 0.0 = {1 / zero}, 0 / 0.0 = {0 / zero}");

// some functions of the Math class
double x, y = 4;
x = Math.Sqrt(y);
Console.WriteLine($"Math.Sqrt(4) = {x}");
Console.WriteLine($"Math.Pow(2, 10) = {Math.Pow(2, 10)}");
Console.WriteLine($"Math.Abs(-3.5) = {Math.Abs(-3.5)}, Math.Max(3, 7) = {Math.Max(3, 7)}");
Console.WriteLine($"Math.PI = {Math.PI}, Math.Cos(Math.PI) = {Math.Cos(Math.PI)}");
Console.WriteLine($"Math.Exp(1) = {Math.Exp(1)}, Math.Log(Math.E) = {Math.Log(Math.E)}");
Console.WriteLine($"Math.Floor(-2.5) = {Math.Floor(-2.5)}, Math.Ceiling(-2.5) = {Math.Ceiling(-2.5)}, Math.Truncate(-2.5) = {Math.Truncate(-2.5)}");
// by default Math.Round rounds to the nearest even number
Console.WriteLine($"Math.Round(2.5) = {Math.Round(2.5)}, Math.Round(3.5) = {Math.Round(3.5)}");
Console.WriteLine($"Math.Round(2.5, MidpointRounding.AwayFromZero) = {Math.Round(2.5, MidpointRounding.AwayFromZero)}");
Console.WriteLine($"Math.Round(2.567, 2) = {Math.Round(2.567, 2)}");

// precedence: * / % before + -
Console.WriteLine($"2 + 3 * 4 = {2 + 3 * 4}, (2 + 3) * 4 = {(2 + 3) * 4}, 10 - 4 - 3 = {10 - 4 - 3}");

// assignment is an expression: multiple assignment
int v1, v2;
v1 = v2 = 7 * 6;
Console.WriteLine($"v1={v1}, v2={v2}");

Results:

> dotnet run basics-11.cs
5 / 2 = 2, 5.0 / 2 = 2,5, 5 / 2.0 = 2,5
5 % 2 = 1, -5 % 2 = -1, 5.5 % 2 = 1,5
1 / 0.0 = ∞, 0 / 0.0 = NaN
Math.Sqrt(4) = 2
Math.Pow(2, 10) = 1024
Math.Abs(-3.5) = 3,5, Math.Max(3, 7) = 7
Math.PI = 3,141592653589793, Math.Cos(Math.PI) = -1
Math.Exp(1) = 2,718281828459045, Math.Log(Math.E) = 1
Math.Floor(-2.5) = -3, Math.Ceiling(-2.5) = -2, Math.Truncate(-2.5) = -2
Math.Round(2.5) = 2, Math.Round(3.5) = 4
Math.Round(2.5, MidpointRounding.AwayFromZero) = 3
Math.Round(2.567, 2) = 2,57
2 + 3 * 4 = 14, (2 + 3) * 4 = 20, 10 - 4 - 3 = 3
v1=42, v2=42

Comments:

line 3: the division of two integers is an integer division;
line 5: the remainder has the same sign as the dividend; the % operator also applies to real numbers;
line 8: dividing a real number by zero does not cause an error; it returns infinity (displayed as ∞) or the special value NaN (“Not a Number”) for 0/0. However, dividing an integer by zero throws a [DivideByZeroException] exception;
lines 11–12: the example above;
Line 18: [Floor] rounds down, [Ceiling] rounds up, [Truncate] rounds to zero;
line 20: by default, [Math.Round] rounds a value that is exactly halfway to the nearest even number (“banker’s” rounding): 2.5 becomes 2 and 3.5 becomes 4;
line 21: for the rounding method taught in school (2.5 becomes 3), specify the rounding mode;
line 25: operator precedence, as shown below;
line 29: a multiple assignment.

3.4.5.3. Order of Operations in Evaluating Arithmetic Expressions

The order of operations when evaluating an arithmetic expression is as follows (from highest to lowest priority):

1	`[functions], [( )], [*, /, %], [+, -]`

Operators within the same block [ ] have the same precedence. When precedence is equal, evaluation proceeds from left to right: 10 - 4 - 3 evaluates to (10 - 4) - 3 = 3.

3.4.5.4. Relational Expressions

The operators are as follows: <, <=, ==, !=, >, >=. Their precedence is:

>, >=, <, <=;
==, !=.

The result of a relational expression is the Boolean [false] if the expression is false, and [true] otherwise.

bool end;
int x = 5;
end = x > 4;

Comparing Two Characters

Let C1 and C2 be two characters. They can be compared using the operators <, <=, ==, !=, >, >=. In this case, it is their Unicode codes—which are numbers—that are compared. According to the Unicode order, the following relationships hold:

1	`space < .. < '0' < '1' < .. < '9' < .. < 'A' < 'B' < .. < 'Z' < .. < 'a' < 'b' < .. < 'z' < .. < 'é'`

Comparison of Two Strings

They are compared character by character. The first inequality encountered between two characters results in an inequality of the same direction for the strings. Consider comparing the strings "Cart" and "Cat":

"Cart"    "Cat"
---------------------
'C'   =   'C'
'a'   =   'a'
'r'   <   't'

This last inequality allows us to conclude that "Cart" < "Cat." Consider comparing the strings "Cat" and "Catkin." They are equal until the string "Cat" is exhausted. In this case, the exhausted string is declared the "smaller" one. We therefore have the relation "Cat" < "Catkin."

Functions for Comparing Two Strings

You can use the relational operators == and != to test whether two strings are equal, or the method [Equals] of the class [System.String]. For the relations <, <=, >, and >=, the operators do not apply to strings: you must use the [CompareTo] method of the [System.String] class or the static [string.Compare] method. They return an integer:

zero if the two strings are equal;
positive if string #1 is greater than string #2;
negative if string #1 is less than string #2.

There is a subtlety: [CompareTo] and [string.Compare] do not simply compare Unicode codes. They follow the sorting rules of the current culture, as in a dictionary: in French, “élan” comes before “face,” even though the code for ‘é’ (233) is greater than that for ‘f’ (102). To choose the comparison mode, [string.Compare] and [Equals] accept a parameter of type [StringComparison]:

[StringComparison.Ordinal]: character-by-character comparison of Unicode codes. This is the fastest comparison and should be used for identifiers, keywords, and filenames;
[StringComparison.OrdinalIgnoreCase]: same as above, ignoring case;
[StringComparison.CurrentCulture] (the default for [CompareTo]): follows standard cultural conventions for sorting text intended for users.

The == operator and the [Equals] method without parameters perform an ordinal comparison.

The program [basics-12.cs] is as follows:

// relational expressions and string comparison
int x = 5;
bool end = x > 4;
Console.WriteLine($"x > 4 : {end}, x == 5 : {x == 5}, x != 5 : {x != 5}");

// comparison of characters: their Unicode codes are compared
Console.WriteLine($"'a' < 'b' : {'a' < 'b'}, 'Z' < 'a' : {'Z' < 'a'}, '9' < 'A' : {'9' < 'A'}");
Console.WriteLine($"codes : 'A'={(int)'A'}, 'a'={(int)'a'}, 'é'={(int)'é'}");

// comparison of strings
string string1 = "cat", string2 = "dog";
int n = string1.CompareTo(string2);
bool equal = string1.Equals(string2);
Console.WriteLine($"n={n}, equal={equal}");
Console.WriteLine($"\"dog\"==string1 : {"dog" == string1}, \"dog\"!=string2 : {"dog" != string2}");
Console.WriteLine($"\"Cat\".CompareTo(\"Catkin\") : {"Cat".CompareTo("Catkin")}");

// CompareTo and string.Compare follow the rules of the current culture (fr-FR)
Console.WriteLine($"\"élan\".CompareTo(\"face\") : {"élan".CompareTo("face")}");
Console.WriteLine($"string.Compare(\"Cat\", \"cat\") : {string.Compare("Cat", "cat")}");
// StringComparison.Ordinal: comparison of the Unicode codes, character by character
Console.WriteLine($"Ordinal(\"élan\", \"face\") : {string.Compare("élan", "face", StringComparison.Ordinal)}");
Console.WriteLine($"Ordinal(\"Cat\", \"cat\") : {string.Compare("Cat", "cat", StringComparison.Ordinal)}");
// ignoring case (upper / lower case)
Console.WriteLine($"OrdinalIgnoreCase(\"Cat\", \"cat\") : {string.Compare("Cat", "cat", StringComparison.OrdinalIgnoreCase)}");
Console.WriteLine($"\"Cat\".Equals(\"cat\") : {"Cat".Equals("cat")}");
Console.WriteLine($"\"Cat\".Equals(\"cat\", OrdinalIgnoreCase) : {"Cat".Equals("cat", StringComparison.OrdinalIgnoreCase)}");

Results:

> dotnet run basics-12.cs
x > 4 : True, x == 5 : True, x != 5 : False
'a' < 'b' : True, 'Z' < 'a' : True, '9' < 'A' : True
codes : 'A'=65, 'a'=97, 'é'=233
n=-1, equal=False
"dog"==string1 : False, "dog"!=string2 : False
"Cat".CompareTo("Catkin") : -1
"élan".CompareTo("face") : -1
string.Compare("Cat", "cat") : 1
Ordinal("élan", "face") : 131
Ordinal("Cat", "cat") : -32
OrdinalIgnoreCase("Cat", "cat") : 0
"Cat".Equals("cat") : False
"Cat".Equals("cat", OrdinalIgnoreCase) : True

Comments:

line 3: a relational expression;
line 7: character comparison;
line 8: the [(int)] conversion of a character returns its Unicode code;
line 12: the variable [n] is assigned a negative integer because "cat" < "dog";
line 13: the variable [equal] has the value [true] if the two strings are equal, [false] otherwise;
Line 15: The operators == and != are used to check whether two strings are equal. In a string interpolation, \" represents a quotation mark;
line 16: the string that is exhausted first is the shorter one;
Lines 19–20: Comparisons based on French conventions: “élan” comes before “face,” and “Cat” comes after “cat” (when the number of letters is the same, lowercase letters come before uppercase ones);
lines 22–23: ordinal comparisons: the result here is the difference between the codes of the first differing characters: 233 – 102 = 131 and 67 – 99 = –32;
lines 25–27: when case is ignored, “Cat” and “cat” are equal.

3.4.5.5. Boolean expressions

The operators that can be used are AND (&&), OR (||), and NOT (!). The result of a Boolean expression is a Boolean value. Operator precedence:

! ;
&& ;
||.

double x = 3.5;
bool valid = x > 2 && x < 4;

Relational operators have higher precedence than the && and || operators. These two operators evaluate their right-hand operand only if necessary: in [a && b], b is not evaluated if a is false; in [a || b], b is not evaluated if a is true. This is called “short-circuit evaluation.” Therefore, it is safe to write [text != null && text.Length > 0].

3.4.5.6. Bitwise Operations

Let [i] and [j] be two integers:

Operation	Role
i << n	Shifts i n bits to the left. The incoming bits are zeros
i >> n	Shift i n bits to the right. If i is a signed integer ([sbyte], [short], [int], [long]), the sign bit is preserved
i >>> n	unsigned right shift (C# 11): the incoming bits are zeros, even if i is signed
i & j	performs the bitwise logical AND of i and j
i \| j	performs the bitwise logical OR of i and j
~i	complements i to 1
i ^ j	performs the EXCLUSIVE OR operation on i and j bit by bit

The program [basics-13.cs] is as follows:

// bit manipulation
short i = 100, j = -13;
ushort k = 0xF123;
Console.WriteLine("i=0x{0:x4}, j=0x{1:x4}, k=0x{2:x4}", i, j, k);
Console.WriteLine("i<<4=0x{0:x4}, i>>4=0x{1:x4}, k>>4=0x{2:x4}", i << 4, i >> 4, k >> 4);
Console.WriteLine("i&j=0x{0:x4}, i|j=0x{1:x4}, i^j=0x{2:x4}, ~i=0x{3:x4}",
    (short)(i & j), (short)(i | j), (short)(i ^ j), (short)~i);
Console.WriteLine("j<<2=0x{0:x4}, j>>2=0x{1:x4}", (short)(j << 2), (short)(j >> 2));
// the same values in binary (B format, .NET 8)
Console.WriteLine($"i={i:B16}, j={j:B16}, i&j={(short)(i & j):B16}");
// unsigned right shift >>> (C# 11): the incoming bits are zeros
int m = -16;
Console.WriteLine($"m={m:B32}, m>>2={m >> 2:B32}, m>>>2={m >>> 2:B32}");

Results:

> dotnet run basics-13.cs
i=0x0064, j=0xfff3, k=0xf123
i<<4=0x0640, i>>4=0x0006, k>>4=0x0f12
i&j=0x0060, i|j=0xfff7, i^j=0xff97, ~i=0xff9b
j<<2=0xffcc, j>>2=0xfffc
i=0000000001100100, j=1111111111110011, i&j=0000000001100000
m=11111111111111111111111111110000, m>>2=11111111111111111111111111111100, m>>>2=00111111111111111111111111111100

Comments:

line 4: the format {0:x4} displays parameter #0 in hexadecimal (x) with 4 digits (4);
line 7: operations on the bits of a [short] result in a [int]; these are converted back to [short] to display 4 hexadecimal digits. Without conversion, ~i would be displayed as 8 digits (ffffff9b);
line 10: the B16 format displays a 16-digit binary integer. We check, bit by bit, the logical AND of i and j;
line 13: the [>>] shift preserves the sign bit of m, which is negative; the [>>>] shift fills with zeros.

3.4.5.7. Combination of Operators

[a = a + b] can be written as [a += b]; [a = a - b] can be written as [a -= b]. The same applies to the operators /, %, *, <<, >>, >>>, &, |, ^. Thus, [a = a / 2;] can be written as [a /= 2;].

3.4.5.8. Increment and Decrement Operators

The notation [variable++] means [variable = variable + 1] or [variable += 1]. The notation [variable--] means [variable = variable - 1] or [variable -= 1]. When used in an expression, these operators have two forms:

[i++] (postfix): the value of the expression is the value of i before the increment;
[++i] (prefixed): the value of the expression is the value of i after the increment.

3.4.5.9. The ternary operator ?:

The expression [expr_cond ? expr1 : expr2] is evaluated as follows:

The expression [expr_cond] is evaluated. This is a Boolean expression;
if it is true, the value of the expression is that of [expr1], and [expr2] is not evaluated;
if it is false, the opposite occurs: the value of the expression is that of [expr2], and [expr1] is not evaluated.

The operation [i = (j > 4 ? j + 1 : j - 1);] will assign j+1 to the variable i if j > 4, and j-1 otherwise. This is the same as writing [if (j > 4) i = j + 1; else i = j - 1;], but it is more concise.

3.4.5.10. The operators ??, ??=, and ?.

These operators make it easier to work with values [null]:

[a ?? b] (C# 2) evaluates to a if a is not equal to [null], and b otherwise. It is used to provide a fallback value: [string name = Console.ReadLine() ?? "";]. The result is no longer nullable;
[a ??= b] (C# 8) assigns b to a only if a is equal to [null];
[a?.Member] (C# 6) is [null] if a is [null], otherwise [a.Member]. Thus, [text?.Length] does not cause an error when [text] is equal to [null]; the result is of type [int?].

The program [basics-14.cs] combines these different operators:

// other operators
// boolean expressions
double x = 3.5;
bool valid = x > 2 && x < 4;
Console.WriteLine($"valid={valid}, !valid={!valid}, valid || x > 10 : {valid || x > 10}");

// compound operators
int a = 10;
a += 5;
Console.Write($"a += 5 : {a}");
a *= 2;
Console.Write($", a *= 2 : {a}");
a /= 4;
Console.Write($", a /= 4 : {a}");
a %= 4;
Console.Write($", a %= 4 : {a}");
a <<= 2;
Console.WriteLine($", a <<= 2 : {a}");

// increment and decrement
int i = 5;
int j = i++;    // j receives the old value of i, then i is incremented
int k = ++i;    // i is incremented, then k receives the new value of i
Console.WriteLine($"i={i}, j={j}, k={k}");
i--;
Console.WriteLine($"i={i}");

// ternary operator
int n = 5;
int p = n > 4 ? n + 1 : n - 1;
string parity = n % 2 == 0 ? "even" : "odd";
Console.WriteLine($"p={p}, {n} is {parity}");

// ?? operator: replacement value if the left operand is null
string? input = null;
string name = input ?? "unknown";
int? age = null;
int displayedAge = age ?? -1;
Console.WriteLine($"name={name}, displayedAge={displayedAge}");
// ??= operator: assignment only if the variable is null
string? title = null;
title ??= "Untitled";
title ??= "Other title";
Console.WriteLine($"title={title}");
// ?. operator: access to a member only if the object is not null
string? text = null;
int? length = text?.Length;
Console.WriteLine($"length={length?.ToString() ?? "null"}");
text = "hello";
Console.WriteLine($"length={text?.Length}");

Results:

> dotnet run basics-14.cs
valid=True, !valid=False, valid || x > 10 : True
a += 5 : 15, a *= 2 : 30, a /= 4 : 7, a %= 4 : 3, a <<= 2 : 12
i=7, j=5, k=7
i=6
p=6, 5 is odd
name=unknown, displayedAge=-1
title=Untitled
length=null
length=5

Comments:

line 4: a Boolean expression;
lines 9–17: combined operators: 10+5=15, 15*2=30, 30/4=7 (integer division), 7%4=3, 3<<2=12;
line 22: [j] is assigned 5, then [i] is set to 6;
line 23: [i] goes to 7, then [k] receives 7;
lines 30–31: two ternary operators;
line 36: [input] equals [null]: [name] receives "unknown". The type of [name] is [string], not [string?];
line 38: the ?? operator allows you to convert from a [int?] to a [int] without risking an exception;
Lines 42–43: The first assignment occurs because [title] is equal to [null]; the second assignment does not occur;
line 47: [text] equals [null], so [length] does too;
line 48: the operators are combined: if [length] equals [null], the string "null" is displayed.

3.4.5.11. General Operator Precedence

The following table lists the operator precedence, from highest to lowest:

Operators	Associativity
[x.y] [x?.y] [f(x)] [a[i]] [x++] [x--] [new] [typeof] [checked] [nameof]	lr
[+x] [-x] [!x] [~x] [++x] [--x] [^x] [(T)x] (type change)	rl
[x..y] (range)	lr
[switch] (switch expression)	lr
*[] [/] [%]**	lr
[+] [-]	lr
[<<] [>>] [>>>]	lr
[<] [<=] [>] [>=] [is] [as]	lr
[==] [!=]	lr
[&]	lr
[^]	lr
[\|]	lr
[&&]	lr
[\|\|]	lr
[??]	rl
[? :] (ternary)	rl
[=] [+=] [-=] [??=] etc., [=>]	rl

lr indicates that, when operators have equal precedence, left-to-right precedence is observed: when an expression contains operators of the same precedence, the operator farthest to the left is evaluated first. rl indicates right-to-left precedence. When in doubt, don’t hesitate to use parentheses: they also make the expression more readable.

3.4.5.12. Type Casting

In an expression, it is possible to temporarily change the representation of a value. This is called “type casting.” The syntax for changing the type of a value in an expression is as follows:

1	`(type) value`

The value then takes on the specified type. This results in a change in the value’s representation. We distinguish between:

Implicit conversions, performed automatically by the compiler when they do not result in any loss of information: from a [int] to a [long], from a [int] to a [double], from a [char] to a [int], and so on. The conversion from a [long] to a [double] is also implicit, although it may lose precision beyond 2⁵³;
explicit conversions, which may result in a loss of information and must be explicitly requested by the programmer using the (type) notation: from a [double] to a [int] (the decimal part is lost), from a [long] to a [int] (the most significant bits are lost), etc.

By default, an overflow in an integer calculation or an integer conversion is not reported: the result is simply false. The keyword [checked], on the other hand, causes an overflow to trigger a [OverflowException] exception. It applies to an expression, [checked(expression)], or to a block of instructions, [checked { ... }].

The program [basics-15.cs] is as follows:

// type changes
int i = 3, j = 4;
float f1 = i / j;
float f2 = (float)i / j;
Console.WriteLine($"f1={f1}, f2={f2}");

// implicit conversions: without loss of information
long l = i;
double d = l;
Console.WriteLine($"l={l}, d={d}");

// explicit conversions (cast): possible loss of information
double real = 3.99;
int truncated = (int)real;
int rounded = (int)Math.Round(real);
Console.WriteLine($"(int)3.99={truncated}, (int)Math.Round(3.99)={rounded}");
long large = 3_000_000_000;
int overflowed = (int)large;
Console.WriteLine($"(int)3000000000={overflowed}");

// characters and integers
char c = (char)65;
int code = 'é';
Console.WriteLine($"(char)65={c}, code of 'é'={code}");

// overflow: silent by default
int max = int.MaxValue;
int next = max + 1;
Console.WriteLine($"int.MaxValue + 1 = {next}");
// checked: the overflow causes an exception
try
{
    int verified = checked(max + 1);
    Console.WriteLine($"verified={verified}");
}
catch (OverflowException e)
{
    Console.WriteLine($"checked(max + 1) : {e.GetType().Name} - {e.Message}");
}
try
{
    checked
    {
        int conversion = (int)large;
        Console.WriteLine($"conversion={conversion}");
    }
}
catch (OverflowException e)
{
    Console.WriteLine($"checked((int)large) : {e.GetType().Name} - {e.Message}");
}

Results:

> dotnet run basics-15.cs
f1=0, f2=0,75
l=3, d=3
(int)3.99=3, (int)Math.Round(3.99)=4
(int)3000000000=-1294967296
(char)65=A, code of 'é'=233
int.MaxValue + 1 = -2147483648
checked(max + 1) : OverflowException - Arithmetic operation resulted in an overflow.
checked((int)large) : OverflowException - Arithmetic operation resulted in an overflow.

Comments:

Line 3: [f1] will have the value 0. The division 3/4 is an integer division since both operands are of type [int]; its result, 0, is then converted to [float];
Line 4: [(float)i] is the value of [i] converted to [float]. We now have a division between a real number of type [float] and an integer of type [int]: the value of [j] is also transformed into [float], and then the two real numbers are divided. [f2] has a value of 0.75. In the operation [(float)i], [i] is a value encoded exactly as a 4-byte number, while [(float)i] is the same value encoded as an approximate 4-byte real number. This transcoding occurs only during the calculation: the variable [i] always retains its type [int];
lines 8–9: implicit conversions;
line 14: converting a floating-point number to an integer truncates the decimal part;
line 15: to round, we use [Math.Round], which yields a [double], then we convert;
line 18: 3 billion does not fit into a [int]: only the least significant 32 bits are retained, and the result no longer makes sense;
Lines 22–23: Conversions between characters and Unicode codes; the second is implicit;
line 28: the capacity overflow goes unnoticed: the smallest possible [int] is obtained;
line 33: with [checked], the overflow triggers a [OverflowException] exception;
lines 42–45: a block of [checked]: the conversion of [large] to [int] also throws an exception.

If the overflow occurs in an expression consisting solely of constants, such as [int.MaxValue + 1], the compiler detects it and rejects the program.

3.5. Program Flow Control Statements

3.5.1. Stop

The [Exit] method of the [Environment] class allows you to stop the execution of a program:

Environment.Exit(int status);

[Exit] terminates the current process and returns control to the calling process, which is typically the command interpreter. The value of [status], known as the return code, can be used by the command interpreter. By convention, 0 indicates that the program completed successfully, while any other value indicates an error. On Windows, the return code is available in the [%ERRORLEVEL%] variable at the command prompt and in the [$LASTEXITCODE] variable within PowerShell; on Linux and macOS, it is available in the [$?] variable of the shell. Thus:

Environment.Exit(0);

will terminate the program with a return code of 0. With high-level statements, a [return] statement also terminates the program (return code 0), unless it is located within a function.

The program [basics-16.cs] receives its return code as an argument:

// stopping the program with an exit code
Console.WriteLine("Start of the program");
// the exit code is passed as an argument (see the section on program arguments)
if (args.Length == 0 || !int.TryParse(args[0], out int code))
{
    Console.Error.WriteLine("Syntax : dotnet run basics-16.cs -- exit_code");
    Environment.Exit(1);
    return;
}
Console.WriteLine($"Stopping with exit code {code}");
Environment.Exit(code);
Console.WriteLine("This line is never executed");

Results in a bash terminal:

> dotnet run basics-16.cs -- 3
Start of the program
Stopping with exit code 3
> echo $?
3
> dotnet run basics-16.cs
Start of the program
Syntax : dotnet run basics-16.cs -- exit_code
> echo $?
1

Comments:

line 4: We check that an argument has been passed and that it is an integer. The program’s arguments are described later;
line 7: if this is not the case, the program terminates with a return code of 1;
line 8: this instruction will never be executed, but the compiler does not know that [Environment.Exit] never returns control. Without it, the compiler would assume that the next line could be reached with an uninitialized [code] variable and would reject the program;
line 11: terminates with the return code passed as an argument. The following line is not executed;
lines 4–9: The command [echo $?] displays the return code of the last program executed: 3, then 1.

3.5.2. Simple decision structure

if (condition)
{
    actions_condition_true;
}
else
{
    actions_condition_false;
}

Notes:

the condition is enclosed in parentheses;
each action ends with a semicolon;
curly braces are not followed by a semicolon;
curly braces are only required if there is more than one action; however, they are often included even for a single action, for readability and to avoid errors when adding an action;
the clause [else] may be omitted;
there is no [then] keyword.

The algorithmic equivalent of this structure is the if...then...else structure:

if condition
    then actions_condition_true
    else actions_condition_false
endif

Example:

if (x > 0) { nx = nx + 1; sx = sx + x; } else dx = dx - x;

Choice structures can be nested. This sometimes leads to the problem illustrated by the program [basics-17.cs]:

// simple choice structure if
int n = 5;
// an else always belongs to the nearest if
if (n > 1)
    if (n > 6)
        Console.WriteLine(">6");
    else
        Console.WriteLine("<=6");

// with braces, the else is attached to the first if
int n2 = 0;
if (n2 > 1)
{
    if (n2 > 6)
    {
        Console.WriteLine(">6");
    }
}
else
{
    Console.WriteLine("<=1");
}

// a sequence of choices: else if
int grade = 13;
string honours;
if (grade < 10)
{
    honours = "failed";
}
else if (grade < 12)
{
    honours = "pass";
}
else if (grade < 14)
{
    honours = "fairly good";
}
else
{
    honours = "good";
}
Console.WriteLine($"grade={grade}, honours={honours}");

Results:

> dotnet run basics-17.cs
<=6
<=1
grade=13, honours=fairly good

Comments:

Lines 4–8: Which [if] does the [else] on line 7 refer to? The rule is that a [else] always refers to the nearest [if]: [if (n > 6)], line 5. The code indentation, which has no effect on the compiler, was chosen to illustrate this;
lines 12–21: here, we wanted to place a [else] next to [if (n2 > 1)], and not a [else] next to [if (n2 > 6)]. Because of the previous rule, we are required to enclose [if (n2 > 1) { ... }] in curly braces;
lines 27–41: a sequence of mutually exclusive choices is written using successive [else if]. The conditions are tested in order; the first true condition determines the action to be executed.

3.5.3. Case Structure

3.5.3.1. The switch statement

The syntax is as follows:

switch (expression)
{
    case v1:
        actions1;
        break;
    case v2:
        actions2;
        break;
    ...
    default:
        actions_otherwise;
        break;
}

Notes:

The value of the control expression in [switch] can be an integer, a character, a character string, an enumeration value, etc.;
the control expression is enclosed in parentheses;
The clause [default] may be absent;
the values vi are possible values of the expression. If the expression evaluates to vi, the actions following the clause [case vi] are executed;
the statement [break] exits the case structure;
Each block of statements associated with a value vi must end with a branch statement ([break], [return], [throw], ...); otherwise, the compiler reports an error. However, multiple [case] clauses can follow one another without any instructions between them: in this case, they share the same actions.

Example in algorithmics:

depending on the value of choice
    case 0
        end of the module
    case 1
        execute module M1
    case 2
        execute module M2
    otherwise
        error <- true
endcase

3.5.3.2. The switch expression

Very often, a case structure is used solely to select a value. C# 8 introduced the switch expression for this purpose:

result = expression switch
{
    pattern1 => value1,
    pattern2 => value2,
    ...
    _ => value_otherwise
};

The expression is compared successively to the patterns; the value associated with the first matching pattern is the result. The pattern \_ matches all values: it acts as a wildcard. A pattern can be:

a constant: [0], ["saturday"];
a relational pattern (C# 9): [< 0], [>= 18];
a combination of patterns with [and], [or], and [not] (C# 9): [> 0 and <= 10], ["saturday" or "sunday"].

These same patterns are used with the operator [is]: [day is "saturday" or "sunday"] is true if [day] is "saturday" or "sunday". We will see other forms of these in the following chapters.

The program [basics-18.cs] is as follows:

// case structure: switch statement and switch expression
int choice = 2;
bool error = false;
switch (choice)
{
    case 0:
        return;
    case 1:
        M1();
        break;
    case 2:
        M2();
        break;
    default:
        error = true;
        break;
}
Console.WriteLine($"error={error}");

// several values for the same case, expression of type string
string day = "saturday";
switch (day)
{
    case "saturday":
    case "sunday":
        Console.WriteLine($"{day} : weekend");
        break;
    default:
        Console.WriteLine($"{day} : weekday");
        break;
}

// switch expression (C# 8): it returns a value
string dayType = day switch
{
    "saturday" or "sunday" => "weekend",
    "monday" or "tuesday" or "wednesday" or "thursday" or "friday" => "weekday",
    _ => "unknown day"
};
Console.WriteLine($"{day} : {dayType}");

// relational patterns (<, <=, >, >=) and logical patterns (and, or, not) (C# 9)
Console.WriteLine($"-5 : {Classify(-5)}");
Console.WriteLine($"0 : {Classify(0)}");
Console.WriteLine($"7 : {Classify(7)}");
Console.WriteLine($"42 : {Classify(42)}");
Console.WriteLine($"1000 : {Classify(1000)}");
// the not pattern
bool workingDay = day is not ("saturday" or "sunday");
Console.WriteLine($"{day} working day : {workingDay}");

// local functions used above
static void M1()
{
    Console.WriteLine("M1");
}

static void M2()
{
    Console.WriteLine("M2");
}

static string Classify(int n) => n switch
{
    < 0 => "negative",
    0 => "zero",
    > 0 and <= 10 => "small",
    > 10 and < 100 => "medium",
    _ => "large"
};

Results:

> dotnet run basics-18.cs
M2
error=False
saturday : weekend
saturday : weekend
-5 : negative
0 : zero
7 : small
42 : medium
1000 : large
saturday working day : False

Comments:

lines 4–15: the C# implementation of the algorithm above;
line 7: in the high-level instructions, [return] terminates the program;
lines 24–25: two values for the same actions;
lines 34–38: a switch expression on a string. The patterns are combined with [or];
line 49: the pattern [not] with the operator [is];
lines 53–60: two local functions;
lines 63–69: a local function whose body is a switch expression. The => notation replaces the body enclosed in curly braces and the statement [return]; this is referred to as an expression body. The relational patterns classify the integer [n].

3.5.4. Repetition Structures

3.5.4.1. Known number of repetitions

For structure

The syntax is as follows:

for (i = id; i <= if; i = i + ip)
{
    actions;
}

Notes:

The three arguments of [for] are enclosed in parentheses and separated by semicolons;
Each action in [for] is terminated by a semicolon;
curly braces are only required if there is more than one action;
the curly brace is not followed by a semicolon.

The algorithmic equivalent is the structure for:

1
2
3

for i varying from id to if in steps of ip
    actions
endfor

which can be translated into a while structure:

i <- id
while i <= if
    actions
    i <- i + ip
endwhile

Foreach structure

The syntax is as follows:

foreach (Type variable in collection)
{
    instructions;
}

Notes:

[collection] is an enumerable collection of objects. The enumerable collection we are already familiar with is the array; we will see others ([List<T>], [Dictionary<K, V>], ...) in Chapter 5;
[Type] is the type of the objects in the collection. For an array, this would be the type of the array elements. We can write [var] instead;
[variable] is a local variable for the loop that will successively take on all the values in the collection. It cannot be modified within the loop.

3.5.4.2. Unknown number of iterations

While loop

while (condition)
{
    actions;
}

The loop continues as long as the condition is true. The loop may never be executed. The notes are the same as for [for]. The corresponding algorithmic structure is the while structure:

1
2
3

while condition
    actions
endwhile

"Do While" Loop

The syntax is as follows:

do
{
    instructions;
} while (condition);

The loop continues until the condition becomes false. Here, the loop is executed at least once. The corresponding algorithmic structure is the “repeat … until” structure:

1
2
3

repeat
    actions
until not condition

General loop structure (for)

The syntax is as follows:

for (start_instructions; condition; end_of_loop_instructions)
{
    instructions;
}

The loop continues as long as the condition is true (evaluated before each iteration). The [start_instructions] statements are executed before entering the loop for the first time. The [end_of_loop_instructions] statements are executed after each iteration of the loop. The various instructions in [start_instructions] and [end_of_loop_instructions] are separated by commas. The corresponding algorithmic structure is as follows:

start_instructions
while condition
    actions
    end_of_loop_instructions
endwhile

3.5.4.3. Loop Control Statements

Instruction	Role
[break]	Exits the loop [for], [foreach], [while], [do ... while]
[continue]	advances to the next iteration of the loops [for], [foreach], [while], [do ... while]

3.5.4.4. Examples

The program [basics-19.cs] is as follows:

// repetition structures
// four ways to compute the sum of the first 10 integers
int i, sum, n = 10;
for (i = 1, sum = 0; i <= n; i = i + 1)
{
    sum = sum + i;
}
Console.WriteLine($"for (1) : sum={sum}");

for (i = 1, sum = 0; i <= n; sum = sum + i, i = i + 1)
{
}
Console.WriteLine($"for (2) : sum={sum}");

i = 1;
sum = 0;
while (i <= n)
{
    sum += i;
    i++;
}
Console.WriteLine($"while : sum={sum}");

i = 1;
sum = 0;
do
{
    sum += i++;
} while (i <= n);
Console.WriteLine($"do while : sum={sum}");

// the loop variable can be declared in the for: it only exists inside the loop
int product = 1;
for (int k = 1; k <= 5; k++)
{
    product *= k;
}
Console.WriteLine($"5! = {product}");

// foreach: iterating over all the elements of a collection
string[] friends = ["paul", "hélène", "jacques", "sylvie"];
foreach (string name in friends)
{
    Console.WriteLine(name);
}

// break and continue
for (int k = 1; k <= 10; k++)
{
    // even numbers are skipped
    if (k % 2 == 0)
    {
        continue;
    }
    // we stop after 7
    if (k > 7)
    {
        break;
    }
    Console.Write($"{k} ");
}
Console.WriteLine();

// infinite loop exited with break: the first multiple of 7 greater than 50
int multiple = 50;
while (true)
{
    multiple++;
    if (multiple % 7 == 0)
    {
        break;
    }
}
Console.WriteLine($"first multiple of 7 greater than 50 : {multiple}");

Results:

> dotnet run basics-19.cs
for (1) : sum=55
for (2) : sum=55
while : sum=55
do while : sum=55
5! = 120
paul
hélène
jacques
sylvie
1 3 5 7 
first multiple of 7 greater than 50 : 56

Comments:

lines 3–30: four ways to calculate the sum of the first 10 integers;
lines 4–8: a classic [for];
lines 10–13: all the work is done in the loop-ending statements; the loop body is empty. The 2008 course used [for (...) ;]: C# accepts this empty statement, but the compiler issues a warning (“possible invalid empty statement”), because a semicolon mistakenly placed after a [for] is a classic error. An empty block { } expresses the same thing unambiguously;
line 28: [i++] returns the value of [i] before it is incremented: [i] is added to [sum], then [i] is incremented;
line 34: the most common form of [for]: the loop variable is declared in [for] and exists only within the loop;
lines 41–42: the loop [foreach] iterates through the elements of the array [friends];
lines 51–58: [continue] moves to the next iteration for even numbers; [break] terminates the loop as soon as [k] exceeds 7;
Lines 66–74: An infinite loop [while (true)] that exits via [break]. This form is convenient when the termination condition is calculated in the middle of the loop. We will use it for keyboard input.

3.6. Exception Handling

Many .NET methods are likely to throw exceptions, i.e., errors. When a method is likely to throw an exception, the programmer should handle it to make programs more error-tolerant: you should always avoid a sudden termination of an application.

3.6.1. The try/catch/finally Structure

Exception handling follows this pattern:

try
{
    code likely to throw an exception
}
catch (Exception e)
{
    handle the exception e
}
next statement

If the code in the [try] block does not throw an exception, execution proceeds to the next statement; otherwise, execution proceeds to the body of the [catch] block, then to the next statement. Note the following points:

[e] is an object of type [Exception] or a derived type. There are many types of exceptions: [IndexOutOfRangeException], [FormatException], [OverflowException], [ArgumentException], etc. By writing [catch (Exception e)], you indicate that you want to handle all types of exceptions. If the code for the [try] clause is likely to generate multiple types of exceptions, you may want to be more specific by handling the exception with multiple [catch] clauses:

try
{
    code likely to throw the exceptions
}
catch (IndexOutOfRangeException e1)
{
    handle the exception e1
}
catch (FormatException e2)
{
    handle the exception e2
}
next statement

The [catch] clauses are evaluated in order; the first one whose type matches the exception is executed. A [catch (Exception e)] clause must therefore be placed last;

a clause [finally] can be added to the clauses [try / catch]:

try
{
    code likely to throw an exception
}
catch (Exception e)
{
    handle the exception e
}
finally
{
    code executed after try or catch
}
next statement

Whether or not an exception occurs, the code in the [finally] clause is always executed. For example, you can use it to close a file;

in clause [catch], you may not want to use the available object [Exception]. Instead of writing [catch (Exception e) { ... }], you would then write [catch (Exception) { ... }] or, more simply, [catch { ... }];
the class [Exception] has a property [Message] that details the error that occurred. To display it, write:

catch (Exception ex)
{
    Console.WriteLine($"The following error occurred: {ex.Message}");
    ...
}

The class [Exception] has a method [ToString] that returns a string indicating the exception type, the value of the [Message] property, and the call stack—that is, the list of methods that were executing at the time of the error, along with the source file name and line number. This is the most useful information for the developer, but it is not intended for the user. In this course, we will most often display the name of the exception type, [ex.GetType().Name], and its message.

3.6.2. A First Example

The program [basics-20.cs] demonstrates an exception generated by accessing a nonexistent array element:

// an exception caused by an incorrect array index
int[] tab = [0, 1, 2, 3];
// displaying the array with a for
for (int i = 0; i < tab.Length; i++)
{
    Console.WriteLine($"tab[{i}]={tab[i]}");
}
// displaying the array with a foreach
foreach (int elmt in tab)
{
    Console.WriteLine(elmt);
}
// generating an exception
try
{
    tab[100] = 6;
}
catch (Exception e)
{
    Console.Error.WriteLine($"The following error occurred: {e.GetType().FullName} - {e.Message}");
    return;
}
finally
{
    Console.WriteLine("finally ...");
}
Console.WriteLine("This line is not executed");

Results:

> dotnet run basics-20.cs
tab[0]=0
tab[1]=1
tab[2]=2
tab[3]=3
0
1
2
3
The following error occurred: System.IndexOutOfRangeException - Index was outside the bounds of the array.
finally ...

Comments:

line 16: this statement throws an exception because the array [tab] does not have an element at index 100;
line 20: the exception is of type [System.IndexOutOfRangeException] (line 10 of the results);
line 21: the program exits;
Lines 23–25: The clause [finally] was executed (line 11 of the results), even though the clause [catch] contained a statement [return]. Note that the [finally] clause is always executed;
line 27: because of [return], this line is not executed.

3.6.3. A controlled entry

Here is another example, [basics-21.cs], where we handle the exception caused by converting a string that does not represent an integer to an integer:

// entering an age with handling of the conversion exception
// we ask for the name
Console.Write("Name: ");
string name = Console.ReadLine() ?? "";
// we ask for the age
int age = 0;
bool ageOK = false;
while (!ageOK)
{
    // question
    Console.Write("age: ");
    // reading-checking the answer
    try
    {
        age = int.Parse(Console.ReadLine() ?? "");
        ageOK = age >= 1;
    }
    catch (FormatException)
    {
    }
    if (!ageOK)
    {
        Console.WriteLine("Incorrect age, try again...");
    }
}
// final display
Console.WriteLine($"Your name is {name} and you are {age} year(s) old");

Results:

> dotnet run basics-21.cs
Name: dupont
age: 23
Your name is dupont and you are 23 year(s) old

> dotnet run basics-21.cs
Name: durand
age: x
Incorrect age, try again...
age: -4
Incorrect age, try again...
age: 12
Your name is durand and you are 12 year(s) old

Comments:

line 4: if the input stream is closed, [ReadLine] returns [null]: it is replaced with an empty string. The variable [name] can therefore be of type [string];
Lines 8–23: the age input loop;
line 15: the line entered via the keyboard is converted to an integer using the [int.Parse] method. This method throws an exception if the conversion is not possible. This is why the operation was placed within a [try / catch];
line 16: If this line is reached, it means the conversion was successful. However, we verify that the resulting integer is greater than or equal to 1;
line 18: if a [FormatException] exception is thrown, control flows to [catch], where no action is taken. Thus, the Boolean variable [ageOK], initialized to [false], remains at [false]. The 2008 course code wrote [catch { }], which catches all exceptions: this is not recommended, because it also masks errors that were not anticipated;
lines 21–23: An error message is displayed if the age is incorrect.

This program has a weakness: an age such as 99999999999 causes a [OverflowException] exception, which is not caught and causes the program to terminate. We could add a [catch] clause; however, it is simpler to use [int.TryParse], as the example application below will do. We will reserve exceptions for truly exceptional situations.

3.6.4. Multiple catch clauses, filters, and exception throws

The program itself can throw an exception using the [throw] statement:

throw new ArgumentException("error message");

Execution of the current method stops, and the exception is propagated up through the calling methods until a [catch] clause handles it; if none does, the program terminates and displays the exception. In a [catch] clause, the [throw;] statement (without parameters) rethrows the current exception, for example, after logging it.

Starting with C# 6, a [catch] clause can be followed by a [when (condition)] filter: the clause is only executed if the condition is true. Starting with C# 7, [throw] can also be used as an expression, to the right of the ?? operator or within a ternary operator.

The program [basics-22.cs] illustrates these possibilities:

// several catch clauses, when filters, throwing exceptions
string[] inputs = ["12", "abc", "", "99999999999", "-3", "150"];
foreach (string input in inputs)
{
    try
    {
        int age = ReadAge(input);
        Console.WriteLine($"[{input}] : age={age}");
    }
    // when filter: the clause is only selected if the condition is true
    catch (FormatException) when (input.Length == 0)
    {
        Console.WriteLine($"[{input}] : empty input");
    }
    catch (FormatException e)
    {
        Console.WriteLine($"[{input}] : {e.GetType().Name} - {e.Message}");
    }
    catch (OverflowException e)
    {
        Console.WriteLine($"[{input}] : {e.GetType().Name} - {e.Message}");
    }
    catch (ArgumentException e)
    {
        Console.WriteLine($"[{input}] : {e.GetType().Name} - {e.Message}");
    }
}

// throw expression (C# 7): to the right of ?? or in a ternary operator
string?[] names = ["dupont", null];
foreach (string? name in names)
{
    try
    {
        string valid = name ?? throw new ArgumentNullException(nameof(name), "the name is mandatory");
        Console.WriteLine($"name={valid}");
    }
    catch (ArgumentNullException e)
    {
        Console.WriteLine($"{e.GetType().Name} - {e.Message}");
    }
}

// a local function that throws exceptions
static int ReadAge(string text)
{
    // int.Parse throws FormatException or OverflowException
    int age = int.Parse(text);
    // we throw an exception ourselves if the age is out of bounds
    if (age < 0 || age > 130)
    {
        throw new ArgumentException($"age out of bounds [0,130] : {age}");
    }
    return age;
}

Results:

> dotnet run basics-22.cs
[12] : age=12
[abc] : FormatException - The input string 'abc' was not in a correct format.
[] : empty input
[99999999999] : OverflowException - Value was either too large or too small for an Int32.
[-3] : ArgumentException - age out of bounds [0,130] : -3
[150] : ArgumentException - age out of bounds [0,130] : 150
name=dupont
ArgumentNullException - the name is mandatory (Parameter 'name')

Comments:

line 2: simulated entries, some valid, some not;
line 7: the local function [ReadAge] can throw several types of exceptions;
line 11: this clause only handles a [FormatException] if the entry is empty;
line 15: the other [FormatException];
line 19: a number that is too large for a [int];
line 23: the exception thrown by [ReadAge] itself;
line 35: an expression [throw]: if [name] is equal to [null], a [ArgumentNullException] exception is thrown. The operator [nameof] (C# 6) returns the name of a variable as a string; [ArgumentNullException] adds it to its message (line 9 of the results);
Line 52: The [ReadAge] function throws an exception if the age is out of bounds.

3.7. Sample Application - V1

We aim to write a program to calculate a taxpayer’s tax liability. We’ll consider the simplified case of a taxpayer who has only a single salary to report. The figures are taken from the 2004 tax schedule for 2003 income and are used as-is: this is a programming exercise, not a calculation of current taxes. This application will serve as our guiding thread: we will revisit it in the following chapters, incorporating classes, files, a database, and then network functionality.

We calculate the number of shares for the employee: shares = nbChildren/2 + 1 if he is unmarried, nbChildren/2 + 2 if he is married, where nbChildren is the number of his children;
if he has at least three children, he receives an additional half-share;
his taxable income R is calculated as R = 0.72 * S, where S is his annual salary;
his family quotient is calculated as QF = R / shares;
his tax I is calculated using the following table:

threshold	coeffR	coeffN
4962	0	0
8382	0.068	291.09
14,753	0.191	1,322.92
23,888	0.283	2,668.39
38,868	0.374	4,846.98
47,932	0.426	6,883.66
0	0.481	9,505.54

Each row has 3 fields. To calculate tax I, find the first row where QF is less than or equal to the limit. For example, if QF = 5,000, the row found will be:

1	`8382 0.068 291.09`

Tax I is then equal to 0.068 * R - 291.09 * shares, truncated to the euro. If QF is such that the condition QF ≤ limit is never satisfied, the coefficients from the last line are used: I = 0.481 * R - 9505.54 * shares. The limit 0 in the last row is therefore never used.

The corresponding C# program [tax-v1.cs] is as follows:

// tax calculation - version 1
// 2004 tax scale (2003 income): this is an exercise, not the current tax scale

// data arrays needed for the tax calculation
decimal[] limits = [4962M, 8382M, 14753M, 23888M, 38868M, 47932M, 0M];
decimal[] coeffR = [0M, 0.068M, 0.191M, 0.283M, 0.374M, 0.426M, 0.481M];
decimal[] coeffN = [0M, 291.09M, 1322.92M, 2668.39M, 4846.98M, 6883.66M, 9505.54M];

// marital status
string answer;
while (true)
{
    Console.Write("Are you married (Y/N)? ");
    answer = (Console.ReadLine() ?? "").Trim().ToLower();
    if (answer is "y" or "n")
    {
        break;
    }
    Console.Error.WriteLine("Incorrect answer. Try again");
}
bool married = answer == "y";

// number of children
int nbChildren;
while (true)
{
    Console.Write("Number of children: ");
    if (int.TryParse(Console.ReadLine(), out nbChildren) && nbChildren >= 0)
    {
        break;
    }
    Console.Error.WriteLine("Incorrect answer. Try again");
}

// annual salary
int salary;
while (true)
{
    Console.Write("Annual salary: ");
    if (int.TryParse(Console.ReadLine(), out salary) && salary >= 0)
    {
        break;
    }
    Console.Error.WriteLine("Incorrect answer. Try again");
}

// number of shares
decimal shares = married ? nbChildren / 2M + 2 : nbChildren / 2M + 1;
if (nbChildren >= 3)
{
    shares += 0.5M;
}

// taxable income
decimal income = 0.72M * salary;

// family quotient
decimal quotient = income / shares;

// search for the tax bracket: the first one such that quotient <= limit,
// the last one if none fits
int i = 0;
while (i < limits.Length - 1 && quotient > limits[i])
{
    i++;
}

// the tax (truncated to the euro)
int tax = (int)(coeffR[i] * income - coeffN[i] * shares);

// displaying the result
Console.WriteLine($"Tax to pay: {tax} euros");

Comments:

Lines 5–7: Numeric values are suffixed with M to be of type [decimal]. The [decimal] type encodes decimal numbers exactly, such as 0.068; this is the type used for financial calculations. With a [double], 0.068 would be only a binary approximation;
lines 10–21: entering marital status, within a [while (true)] loop that exits via [break] when the answer is correct;
line 14: [Console.ReadLine()] returns the string C1 as typed on the keyboard, or [null] (replaced by ""); [C1.Trim()] removes the leading and trailing spaces from C1 and returns the string C2; [C2.ToLower()] returns the string C2 converted to lowercase. This accepts both Y and y;
line 15: a pattern combined with [or];
line 19: error messages are written to the stream [Error];
line 21: the Boolean [married] receives the value [true] or [false] from the relation [answer == "y"];
line 28: [TryParse] returns [false] if the input is not an integer; the condition [nbChildren >= 0] is then not evaluated (the && operator is short-circuited). [TryParse] accepts a string [null]: it then returns [false]. Unlike the 2008 version, no exceptions are used;
line 40: same applies to the salary;
Line 48: You cannot simply write nbChildren / 2: if nbChildren is equal to 3, you would get 3/2, an integer division that would result in 1, not 1.5. Since the divisor 2M is of type [decimal], the division is performed as [decimal]. The 2008 course material used [(decimal)nbChildren / 2], which amounts to the same thing;
Lines 62–65: determining the tax bracket. The calculation stops at the first threshold that is greater than or equal to the family quotient, and no later than the last tax bracket. The 2008 version initially wrote QF in the last cell of the limit table to ensure it stopped: this altered the tax schedule data; the condition [i < limits.Length - 1] avoids this side effect;
Line 69: The tax is truncated to the euro by converting it to [int].

Here are some examples of the output:

> dotnet run tax-v1.cs
Are you married (Y/N)? y
Number of children: 2
Annual salary: 60000
Tax to pay: 4282 euros

> dotnet run tax-v1.cs
Are you married (Y/N)? yes
Incorrect answer. Try again
Are you married (Y/N)? y
Number of children: three
Incorrect answer. Try again
Number of children: 3
Annual salary: 60000 euros
Incorrect answer. Try again
Annual salary: 60000
Tax to pay: 2959 euros

> dotnet run tax-v1.cs
Are you married (Y/N)? n
Number of children: 0
Annual salary: 60000
Tax to pay: 11519 euros

These are the same results as in the 2008 course: 4,282 euros for a married taxpayer with 2 children and 2,959 euros with 3 children, for an annual salary of 60,000 euros. A single person with no children and the same salary pays 11,519 euros. In the second run, the input “60000 euros” is rejected: [int.TryParse] accepts only strings that represent an exact integer (leading and trailing spaces are allowed).

3.8. Main Program Arguments

The main function [Main] can accept an array of strings [string[]] as a parameter. This array contains the command-line arguments used to launch the application. Thus, if program P is launched with the command:

1	`P arg0 arg1 ... argn`

and if the function [Main] is declared as follows:

        static void Main(string[] args)

then we will have args[0]="arg0", args[1]="arg1", and so on. With high-level statements, there is no [Main] method written by the programmer, but the array [args] is available in the same way: it is the parameter of the [Main] method generated by the compiler.

With [dotnet run], the arguments for the program are placed after two dashes ([--]), which separate them from the options of the [dotnet run] command itself:

1	`dotnet run prog.cs -- a0 a1 a2`

The 2008 course specified the arguments in the Visual Studio project properties; today, the command line is sufficient. Here is an example, [basics-23.cs]:

// the command-line arguments
// with top-level statements, the args array is predefined
Console.WriteLine($"There are {args.Length} argument(s)");
for (int i = 0; i < args.Length; i++)
{
    Console.WriteLine($"args[{i}]={args[i]}");
}

Results:

> dotnet run basics-23.cs -- a0 a1 a2 a3
There are 4 argument(s)
args[0]=a0
args[1]=a1
args[2]=a2
args[3]=a3

An argument that contains spaces must be enclosed in quotation marks:

> dotnet run basics-23.cs -- "jean dupont" 23
There are 2 argument(s)
args[0]=jean dupont
args[1]=23

The same program written using a traditional [Main] method: [basics-24.cs]:

// the command-line arguments with a classic Main method
namespace Basics;

public static class Program
{
    public static void Main(string[] args)
    {
        Console.WriteLine($"There are {args.Length} argument(s)");
        for (int i = 0; i < args.Length; i++)
        {
            Console.WriteLine($"args[{i}]={args[i]}");
        }
    }
}

Results:

> dotnet run basics-24.cs -- a0 a1 a2 a3
There are 4 argument(s)
args[0]=a0
args[1]=a1
args[2]=a2
args[3]=a3

Comments:

line 2: a file-scope namespace (C# 10);
line 4: a static class contains only static members;
line 6: the program's entry point. Since this file contains no high-level statements, the compiler looks for a static method named [Main];
line 8: the rest is identical to [basics-23.cs].

The signature [static void Main()] is valid if the function [Main] takes no parameters. [Main] can also return a [int], which is then the program’s return code: [static int Main(string[] args)].

3.9. Enumerations

An enumeration is a data type whose value domain consists of a set of named integer constants. Consider a program that needs to handle exam grades. There are five possible grades: Pass, FairlyGood, Good, VeryGood, and Excellent. We can then define an enumeration for these five constants:

enum Honours { Pass, FairlyGood, Good, VeryGood, Excellent }

Internally, these five constants are encoded as consecutive integers starting with 0 for the first constant, 1 for the next, and so on. We can also set these values explicitly: [enum Honours { Pass = 10, FairlyGood = 12, ... }]. A variable can be declared to take its values from the enumeration:

1	`Honours myHonours = Honours.Pass;`

A variable can be compared to the different possible values in the enumeration:

if (myHonours == Honours.Pass)
{
    Console.WriteLine("Could do better");
}

Just as the simple type [int] is equivalent to the structure [System.Int32], every enumeration derives from the class [System.Enum]. This class has static methods that allow you to retrieve the values and names of an enumerated type:

[Enum.GetValues<Honours>()] (.NET 5) returns the array of values for the enumeration [Honours];
[Enum.GetNames<Honours>()] returns the array of their names;
[Enum.TryParse(str, out Honours m)] converts a string into an enumeration value.

The 2008 course described [Enum.GetValues(typeof(Honours))]: this form, which is still valid, returns an untyped array that must then be converted. The generic form [GetValues<Honours>()] directly returns an array of type [Honours[]].

The program [basics-25.cs] illustrates what has just been described:

// enumerations
// a variable that takes its values from the Honours enumeration
Honours myHonours = Honours.Pass;
// displaying the value of the variable
Console.WriteLine($"honours={myHonours}");
// test with a value of the enumeration
if (myHonours == Honours.Pass)
{
    Console.WriteLine("Could do better");
}
// list of honours: name and integer value
foreach (Honours m in Enum.GetValues<Honours>())
{
    Console.WriteLine($"{m} = {(int)m}");
}
// list of names
Console.WriteLine(string.Join(", ", Enum.GetNames<Honours>()));
// integer --> enumeration
Honours m3 = (Honours)3;
Console.WriteLine($"(Honours)3 = {m3}");
// string --> enumeration
if (Enum.TryParse("Good", out Honours m2))
{
    Console.WriteLine($"m2={m2}, m2 > Pass : {m2 > Honours.Pass}");
}
// an enumeration in a switch expression
string assessment = myHonours switch
{
    Honours.Pass or Honours.FairlyGood => "correct",
    Honours.Good or Honours.VeryGood => "very correct",
    _ => "remarkable"
};
Console.WriteLine($"assessment : {assessment}");
Console.WriteLine($"type : {typeof(Honours).FullName}, underlying type : {Enum.GetUnderlyingType(typeof(Honours)).Name}");

// the declaration of a type is placed after the top-level statements
enum Honours { Pass, FairlyGood, Good, VeryGood, Excellent }

Results:

> dotnet run basics-25.cs
honours=Pass
Could do better
Pass = 0
FairlyGood = 1
Good = 2
VeryGood = 3
Excellent = 4
Pass, FairlyGood, Good, VeryGood, Excellent
(Honours)3 = VeryGood
m2=Good, m2 > Pass : True
assessment : correct
type : Honours, underlying type : Int32

Comments:

line 3: a variable of type [Honours];
line 5: an enumeration value is displayed by its name;
lines 12–14: the list of values. The [(int)m] conversion returns the integer value of the constant;
line 17: the list of names;
line 19: the reverse conversion, from an integer to the enumeration;
line 22: the conversion of a string to an enumeration value. Enumeration values are compared like the integers that encode them;
lines 27–31: enumerations work well with switch statements;
line 34: the underlying integer type is [int] by default;
line 37: the declaration of the enumeration. In a file containing high-level statements, type declarations (enumerations, classes, etc.) are placed after the statements.

An enumeration whose values are powers of 2 (1, 2, 4, 8, ...) can be assigned the attribute [Flags]: its values are then combined using the | operator (bitwise OR) to represent a set of options, for example the access rights to a file (read | write).

3.10. Passing Parameters to a Function

Here we focus on how parameters are passed to a function. Consider the following function:

static void ChangeInt(int a)
{
    a = 30;
    Console.WriteLine($"Formal parameter a={a}");
}

In the function definition, on line 1, [a] is called a formal parameter. It is included solely for the purposes of defining the function [ChangeInt]. It could just as easily have been named [b]. Now let’s consider an example of how this function is used:

int age = 20;
ChangeInt(age);
Console.WriteLine($"Actual parameter age={age}");

Here, in the statement on line 2, [age] is the actual parameter that will pass its value to the formal parameter [a]. We are interested in how a formal parameter retrieves the value of an actual parameter.

3.10.1. Passing Modes

C# supports the following passing modes:

by value (the default mode): the value of the actual parameter is copied into the corresponding formal parameter. These are two distinct entities: if the function modifies the formal parameter, the actual parameter remains unchanged. This mode is suitable for a function’s input parameters;
by reference with [ref]: the actual parameter and the formal parameter are one and the same entity. If the function modifies the formal parameter, the actual parameter is also modified. The keyword [ref] must appear in both the function definition and the call. The actual parameter must have a value before the call. This mode is suitable for input-output parameters;
by reference with [out]: same as [ref], but the parameter is an output-only parameter: the actual parameter does not need an initial value, and the function must assign a value to the formal parameter. This is the mode used by the [TryParse] methods. Starting with C# 7, the variable can be declared in the call: [out var x] or [out int x];
by read-only reference with [in] (C# 7.2): the parameter is passed by reference, which avoids copying, but the function cannot modify it. This mode is only useful for large structures; for predefined types, passing by value is just as efficient.

The program [basics-26.cs] illustrates these different modes:

// parameter passing modes
// 1 - passing by value
int age = 20;
ChangeInt(age);
Console.WriteLine($"Actual parameter age={age}");

// 2 - passing by reference with ref
int age2 = 20;
ChangeInt2(ref age2);
Console.WriteLine($"Actual parameter age2={age2}");

// 3 - passing by reference with out: no need to initialize the variable
int age3;
ChangeInt3(out age3);
Console.WriteLine($"Actual parameter age3={age3}");
// out var (C# 7): the variable is declared in the call
ChangeInt3(out var age4);
Console.WriteLine($"Actual parameter age4={age4}");

// 4 - a swap of values with ref
int x = 1, y = 2;
Swap(ref x, ref y);
Console.WriteLine($"after swap : x={x}, y={y}");

// 5 - read-only passing by reference with in
decimal price = 100M;
Console.WriteLine($"InclTax({price})={InclTax(in price)}");

// 6 - an array passed by value: it is its reference that is copied
int[] array = [1, 2, 3];
ModifyArray(array);
Console.WriteLine($"array=[{string.Join(", ", array)}]");

// the local functions
static void ChangeInt(int a)
{
    a = 30;
    Console.WriteLine($"Formal parameter a={a}");
}

static void ChangeInt2(ref int a2)
{
    a2 = 30;
    Console.WriteLine($"Formal parameter a2={a2}");
}

static void ChangeInt3(out int a3)
{
    a3 = 30;
    Console.WriteLine($"Formal parameter a3={a3}");
}

static void Swap(ref int a, ref int b)
{
    int temp = a;
    a = b;
    b = temp;
}

static decimal InclTax(in decimal amount)
{
    // amount = 0; would be rejected: an in parameter cannot be modified
    return amount * 1.2M;
}

static void ModifyArray(int[] t)
{
    // we modify the referenced array: the caller sees the modification
    t[0] = 100;
    // we make t point to another array: the caller does not see it
    t = [7, 8, 9];
    Console.WriteLine($"in ModifyArray : t=[{string.Join(", ", t)}]");
}

Results:

> dotnet run basics-26.cs
Formal parameter a=30
Actual parameter age=20
Formal parameter a2=30
Actual parameter age2=30
Formal parameter a3=30
Actual parameter age3=30
Formal parameter a3=30
Actual parameter age4=30
after swap : x=2, y=1
InclTax(100)=120,0
in ModifyArray : t=[7, 8, 9]
array=[100, 2, 3]

Comments:

Lines 3–5: The value 20 of the actual parameter [age] was copied to the formal parameter [a] (line 35). This parameter was then modified (line 37). The actual parameter remained unchanged;
lines 8–10: With [ref], the actual parameter [age2] followed the modification of the formal parameter [a2];
lines 13–15: the variable [age3] is not initialized before the call; this is possible with [out];
line 17: the variable [age4] is declared in the call;
lines 21–22: Swapping two values requires passing by reference; with passing by value, the function would swap copies;
line 27: a read-only pass. The keyword [in] is optional in the call. The result 120.0 has one decimal place because the product of two [decimal] values preserves the decimal places of its operands: 100 × 1.2 = 120.0;
Lines 30–32: An array is a reference type; what is passed by value is the array’s reference. The function [ModifyArray] therefore operates on the same array as the caller: the modification made by [t[0]] (line 69) is visible to the caller. However, setting [t] to point to another array (line 71) only modifies the local copy of the reference.

If line 8 is replaced with [int age2;], the compiler rejects the program:

1	`error CS0165: Use of unassigned local variable 'age2'`

This issue can be circumvented by assigning an initial value to [age2], or by replacing the keyword [ref] with the keyword [out]: this indicates that the parameter is solely an output parameter. Similarly, if the function [InclTax] attempts to modify its parameter [in]:

1	`error CS8331: Cannot assign to variable 'amount' or use it as the right hand side of a ref assignment because it is a readonly variable`

3.10.2. Optional parameters, named arguments, variable number of parameters

C# 4 introduced optional parameters: a parameter can be given a default value in the function definition; the caller can then omit it. Optional parameters are placed after the required parameters. It also introduced named arguments: when calling the function, an actual parameter can be preceded by the name of the formal parameter followed by a colon. This allows an optional parameter that precedes other parameters to be omitted, or for parameters to be provided in any order.

The keyword [params] allows you to write a function with a variable number of parameters: the last formal parameter is an array, and the caller can pass either an array or a list of values (which may be empty), which the compiler arranges into an array. Starting with C# 13, the parameter [params] can also be of another collection type, such as [List<T>] or [ReadOnlySpan<T>].

The program [basics-27.cs] is as follows:

// optional parameters, named arguments, variable number of parameters
// optional parameters (C# 4): they have a default value
Console.WriteLine(Greet("Pierre"));
Console.WriteLine(Greet("Pierre", "Good evening"));
// named arguments (C# 4): an optional parameter can be skipped or the order changed
Console.WriteLine(Greet("Pierre", uppercase: true));
Console.WriteLine(Greet(uppercase: true, greeting: "Hi", name: "Paul"));

// params: variable number of parameters
Console.WriteLine($"Sum()={Sum()}");
Console.WriteLine($"Sum(1, 2, 3)={Sum(1, 2, 3)}");
int[] values = [10, 20, 30];
Console.WriteLine($"Sum(values)={Sum(values)}");
// a framework method with a variable number of parameters
Console.WriteLine(string.Join(" - ", "a", "b", "c"));

static string Greet(string name, string greeting = "Hello", bool uppercase = false)
{
    string message = $"{greeting} {name}";
    return uppercase ? message.ToUpper() : message;
}

static int Sum(params int[] numbers)
{
    // numbers is an array
    int sum = 0;
    foreach (int number in numbers)
    {
        sum += number;
    }
    return sum;
}

Results:

> dotnet run basics-27.cs
Hello Pierre
Good evening Pierre
HELLO PIERRE
HI PAUL
Sum()=0
Sum(1, 2, 3)=6
Sum(values)=60
a - b - c

Comments:

Line 17: The function [Greet] has one required parameter, [name], and two optional parameters, [greeting] and [uppercase];
Line 3: Both optional parameters take their default values;
line 4: only [uppercase] takes its default value;
line 6: using the named argument, we pass [uppercase] without passing [greeting];
line 7: With named arguments, the order is arbitrary;
line 23: [Sum] accepts any number of integers;
lines 10–13: [Sum] is called without any parameters, with three integers, and then with an array;
Line 15: Many .NET methods, such as [string.Join] or [Console.WriteLine] with a format, have a [params] parameter.

3.11. Local Functions and Tuples

3.11.1. Local functions

A local function (C# 7) is a function defined within a method or, as in our examples, among top-level statements. It can only be used in that location. Since our programs no longer have classes, local functions replace the static methods from the 2008 examples. A local function:

can be called before it is defined;
can use the local variables surrounding it, unless it is declared as [static]: the [static] keyword (C# 8) ensures that it depends only on its parameters, making it easier to understand. We declare our local functions [static] whenever possible;
may have an expression body: [static int Square(int x) => x * x;] is equivalent to a body like [{ return x * x; }].

In a larger program, we write classes and methods: this is the subject of the next chapter.

3.11.2. Tuples

A tuple (C# 7) groups multiple values—which may be of different types—into a single entity. The type [(int, string)] denotes a pair consisting of an integer and a string; its elements are called [Item1] and [Item2]. They can be named: [(int Number, string Name)]. A tuple can be deconstructed: [var (number, name) = t;] assigns its elements to two variables.

Tuples allow a function to return multiple values without using parameters [out]: this is often more readable.

The program [basics-28.cs] is as follows:

// local functions and tuples
// a local function with an expression body
static int Square(int x) => x * x;
Console.WriteLine($"Square(7)={Square(7)}");

// a non-static local function can use the variables of the program
int counter = 0;
void Increment() => counter++;
Increment();
Increment();
Console.WriteLine($"counter={counter}");

// a tuple groups several values
(int, string) t1 = (1, "one");
Console.WriteLine($"t1={t1}, t1.Item1={t1.Item1}, t1.Item2={t1.Item2}");
// the elements of a tuple can be named
(int Number, string Name) t2 = (2, "two");
var t3 = (Number: 3, Name: "three");
Console.WriteLine($"t2.Number={t2.Number}, t3.Name={t3.Name}");
// deconstruction: a tuple is split into several variables
var (number, name) = t3;
Console.WriteLine($"number={number}, name={name}");

// a function that returns several values without out parameters
var (quotient, remainder) = Divide(17, 5);
Console.WriteLine($"17 = 5 * {quotient} + {remainder}");
var mm = MinMax([12, -4, 35, 7]);
Console.WriteLine($"min={mm.Min}, max={mm.Max}");
// the framework also uses tuples
var (q, r) = Math.DivRem(23, 4);
Console.WriteLine($"Math.DivRem(23, 4) : quotient={q}, remainder={r}");

// swapping two variables with a tuple
int a = 1, b = 2;
(a, b) = (b, a);
Console.WriteLine($"a={a}, b={b}");

static (int Quotient, int Remainder) Divide(int a, int b) => (a / b, a % b);

static (int Min, int Max) MinMax(int[] values)
{
    int min = values[0], max = values[0];
    foreach (int v in values)
    {
        if (v < min) min = v;
        if (v > max) max = v;
    }
    return (min, max);
}

Results:

> dotnet run basics-28.cs
Square(7)=49
counter=2
t1=(1, one), t1.Item1=1, t1.Item2=one
t2.Number=2, t3.Name=three
number=3, name=three
17 = 5 * 3 + 2
min=-4, max=35
Math.DivRem(23, 4) : quotient=5, remainder=3
a=2, b=1

Comments:

line 3: a static local function with an expression body;
lines 7–8: a non-static local function: it modifies the program variable [counter];
line 14: a tuple whose elements are unnamed. When a tuple is printed, its elements appear in parentheses;
lines 17–18: two tuples with named elements: the first by its type, the second by the names given in the expression;
line 21: the unpacking of the tuple [t3];
line 25: the function [Divide] returns the quotient and remainder of the integer division; the result is unpacked directly;
line 27: here, the tuple is retained, and the names of its elements, [Min] and [Max], are used;
line 30: From .NET 6, [Math.DivRem] also returns a tuple (quotient, remainder);
line 35: swapping two variables can be written on a single line using a tuple, without a temporary variable;
line 38: the type returned by the function is a named tuple;
lines 40–48: a function that calculates the minimum and maximum of an array in a single pass.

3. The Basics of the C# Language

3.1. Introduction

3.2. The Minimal Program

3.2.1. High-level instructions

3.2.2. The classic form with a Main method

3.2.3. Implicit using statements

3.3. C# Data

3.3.1. Predefined data types

3.3.2. Notation for Literal Data

3.3.3. Data Declaration

3.3.3.1. Role of declarations

3.3.3.2. Declaring Constants

3.3.3.3. Variable Declaration

3.3.4. Nullable Types

3.3.5. Conversions between numbers and strings

3.3.6. Data Arrays

3.4. Basic C# Statements

3.4.1. Writing to the Screen

3.4.2. Reading Data Entered via the Keyboard

3.4.3. Example of Input/Output

3.4.4. Input/Output Redirection

3.4.5. Assigning the value of an expression to a variable

3.4.5.1. Interpretation of the assignment operation

3.4.5.2. Arithmetic Expressions

3.4.5.3. Order of Operations in Evaluating Arithmetic Expressions

3.4.5.4. Relational Expressions

3.4.5.5. Boolean expressions

3.4.5.6. Bitwise Operations

3.4.5.7. Combination of Operators

3.4.5.8. Increment and Decrement Operators

3.4.5.9. The ternary operator ?:

3.4.5.10. The operators ??, ??=, and ?.

3.4.5.11. General Operator Precedence

3.4.5.12. Type Casting

3.5. Program Flow Control Statements

3.5.1. Stop

3.5.2. Simple decision structure

3.5.3. Case Structure

3.5.3.1. The switch statement

3.5.3.2. The switch expression

3.5.4. Repetition Structures

3.5.4.1. Known number of repetitions

3.5.4.2. Unknown number of iterations

3.5.4.3. Loop Control Statements

3.5.4.4. Examples

3.6. Exception Handling

3.6.1. The try/catch/finally Structure

3.6.2. A First Example

3.6.3. A controlled entry

3.6.4. Multiple catch clauses, filters, and exception throws

3.7. Sample Application - V1

3.8. Main Program Arguments

3.9. Enumerations

3.10. Passing Parameters to a Function

3.10.1. Passing Modes

3.10.2. Optional parameters, named arguments, variable number of parameters

3.11. Local Functions and Tuples

3.11.1. Local functions

3.11.2. Tuples

3.2.3. Implicit `using` statements