Skip to content

Commit 0b8b0a3

Browse files
authored
Small tweaks to structs concept docs (#2346)
1 parent f3c98a6 commit 0b8b0a3

File tree

2 files changed

+30
-12
lines changed

2 files changed

+30
-12
lines changed

concepts/structs/about.md

Lines changed: 27 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,11 @@
11
# About
22

3-
C# `struct`s are closely related `class`s. They have state and behavior. They can have the same kinds of members: constructors, methods, fields, properties, etc.
3+
C# `struct`s are closely related to `class`es.
4+
They have state and behavior.
5+
They can have the same kinds of members: constructors, methods, fields, properties, etc.
46

5-
Fields and properties can be simple types, `struct`s or reference types. `struct`s observe the same rules about scope, read/write rules and access levels as do `class`s.
7+
Fields and properties can be simple types, `struct`s or reference types.
8+
`struct`s observe the same rules about scope, read/write rules and access levels as do `class`es.
69

710
```csharp
811
enum Unit
@@ -32,9 +35,11 @@ new Weight(77.5, Unit.Kg).ToString();
3235
// => "77.6Kg"
3336
```
3437

35-
One of the main things to remember is that when one struct is assigned to a variable or passed as a parameter the values are copied across so changes to the original variable will not affect the copied one and vice versa. In summary, `struct`s are **value types**.
38+
One of the main things to remember is that when one struct is assigned to a variable or passed as a parameter the values are copied across so changes to the original variable will not affect the copied one and vice versa.
39+
In summary, `struct`s are **value types**.
3640

37-
This [article][class-or-struct] discusses the differences between `struct`s and `class`s. You will see from the article that `struct`s tend to be lightweight and [immutable][structs-immutable] although this guidance is not enforced (by default) by the compiler or runtime.
41+
This [article][class-or-struct] discusses the differences between `struct`s and `class`es.
42+
You will see from the article that `struct`s tend to be lightweight and [immutable][structs-immutable] although this guidance is not enforced (by default) by the compiler or runtime.
3843

3944
There are a couple of things that you will come up against (and about which the compiler will remind you):
4045

@@ -46,21 +51,32 @@ As a result of points 1 and 3 above there is no way for the developer of a `stru
4651

4752
## Common structs
4853

49-
You will see from the documentation that there is a close relationship between primitives and structs. See [`Int32/int`][int32], for an example. A more conventional example of a`struct`is the type [`TimeSpan`][time-span].
54+
You will see from the documentation that there is a close relationship between primitives and structs.
55+
See [`Int32/int`][int32], for an example.
56+
A more conventional example of a`struct`is the type [`TimeSpan`][time-span].
5057

51-
Instances of `TimeSpan` behave much like numbers with comparison operators like `>` and `<` and arithmetic operators. You can implement these operators for your own `struct`s when you need them.
58+
Instances of `TimeSpan` behave much like numbers with comparison operators like `>` and `<` and arithmetic operators.
59+
You can implement these operators for your own `struct`s when you need them.
5260

53-
One thing to note about `TimeSpan` is that it implements a number of interfaces e.g. `IComparable<TimeSpan>`. Although `struct`s cannot be derived from other `struct`s they can implement interfaces.
61+
One thing to note about `TimeSpan` is that it implements a number of interfaces e.g. `IComparable<TimeSpan>`.
62+
Although `struct`s cannot be derived from other `struct`s they can implement interfaces.
5463

5564
## Equality
5665

57-
Equality testing for `struct`s can often be much simpler than that for `class`s as it simply compares fields for equality by default. There is no need to override `object.Equals()` (or `GetHashCode()`). Remember that if you are relying on `Object.GetHashCode()` you must still ensure that the fields involved in generating the hash code (i.e. all the fields) must not change while a hashed collection is use. Effectively, this means that structs used in this way should be immutable.
66+
Equality testing for `struct`s can often be much simpler than that for `class`es as it simply compares fields for equality by default.
67+
There is no need to override `object.Equals()` (or `GetHashCode()`).
68+
Remember that if you are relying on `Object.GetHashCode()` you must still ensure that the fields involved in generating the hash code (i.e. all the fields) must not change while a hashed collection is use.
69+
Effectively, this means that structs used in this way should be immutable.
5870

59-
In contrast to the method, `Equals()`, there is no default implementation of the equality operators, `==` and `!=`. If your `struct` needs them then you will have to implement them.
71+
In contrast to the method, `Equals()`, there is no default implementation of the equality operators, `==` and `!=`.
72+
If your `struct` needs them then you will have to implement them.
6073

61-
On the other hand, this [article][equality] describes how performance can be optimised by creating your own custom `Equals()` and `GetHashCode()` method as is often done with `class`s. The difference in the case of this exercise was about 20% in a not very rigorous comparison but that may be on the low side because all the fields are of the same type - see below.
74+
On the other hand, this [article][equality] describes how performance can be optimised by creating your own custom `Equals()` and `GetHashCode()` method as is often done with `class`es.
75+
The difference in the case of this exercise was about 20% in a not very rigorous comparison but that may be on the low side because all the fields are of the same type - see below.
6276

63-
There are discussions on the [web][equality-performance] about speed improvements, where the `Equals()` method is not overridden, if all fields are of the same type. The difference in this exercise of including disparate fields was about 60%. This is not mentioned in Microsoft's documentation so that makes it an un-documented implementation detail, and it should be exploited judiciously.
77+
There are discussions on the [web][equality-performance] about speed improvements, where the `Equals()` method is not overridden, if all fields are of the same type.
78+
The difference in this exercise of including disparate fields was about 60%.
79+
This is not mentioned in Microsoft's documentation so that makes it an un-documented implementation detail, and it should be exploited judiciously.
6480

6581
```csharp
6682
public bool Equals(Weight other)

concepts/structs/introduction.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
# Introduction
22

3-
C# `struct`s are closely related `class`s. They have state and behavior. They have constructors that take arguments, instances can be assigned, tested for equality and stored in collections.
3+
C# `struct`s are closely related to `class`es.
4+
They have state and behavior.
5+
They have constructors that take arguments, instances can be assigned, tested for equality and stored in collections.
46

57
```csharp
68
enum Unit

0 commit comments

Comments
 (0)