From b3fee40ced8ee3804766682a782cac886d337cee Mon Sep 17 00:00:00 2001 From: James Groom Date: Wed, 8 Feb 2023 03:40:25 +1000 Subject: [PATCH] Updated C# and .NET docs supplement (markdown) --- C#-and-.NET-docs-supplement.md | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/C#-and-.NET-docs-supplement.md b/C#-and-.NET-docs-supplement.md index 272ce47..c115d3c 100644 --- a/C#-and-.NET-docs-supplement.md +++ b/C#-and-.NET-docs-supplement.md @@ -1,9 +1,31 @@ To save us repeating our complaints about the lack of proper documentation under each section, let's agree to gather all the frustration here: > AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA -### `System.Drawing.SystemIcons` rendered +## Collection type names + +`IReadOnly{Collection,Dictionary,List,Set}` are for getting read-only views of the collections that implement them. They do not mean the collection is immutable (there are separate classes for that). + +> Kotlin got this right by calling its interfaces e.g. `List`/`MutableList` instead of `IReadOnlyList`/`IList`. (And it also fixed the inheritance hierarchy.) + +## Featureset is determined by language level AND target + +see [feature matrix](https://github.com/TASEmulators/BizHawk/wiki/Available-C%23-and-.NET-features) page + +## `System.Drawing.SystemIcons` rendered [Docs for `SystemIcons`](https://learn.microsoft.com/en-us/dotnet/api/system.drawing.systemicons?view=netframework-4.8) don't include any pictures, so here they are (Win10, Mono 6.12.x): -TODO -![SystemIcons_Mono](https://user-images.githubusercontent.com/13409956/217311223-0d6acd76-203b-4694-9f45-4e4b8acc184b.png) \ No newline at end of file +![SystemIcons_Win10](https://user-images.githubusercontent.com/13409956/217321727-b3527c87-3ad9-44bb-8276-01afde65a939.png) +![SystemIcons_Mono](https://user-images.githubusercontent.com/13409956/217311223-0d6acd76-203b-4694-9f45-4e4b8acc184b.png) + +## Type casting + +There are two types of casts in C#: the C-style `(T) o` throws if the object is not of the desired type; whereas `o as T` evaluates to `null` if it's not of the desired type. There's no '?' in this `null`-producing operator. (This is probably only confusing if you use Kotlin.) + +If an object being the wrong type is *exceptional*, throw an *exception* straight away. Having it reported as an NRE when there's no `null` in sight just delays debugging the problem. + +## Type constraints (`where` clauses) + +`class` in `where` clauses does not mean "not abstract", it means "reference type". Similarly, `struct` means "value type". There's a lot of complexity re: nullability, so [check the docs](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/generics/constraints-on-type-parameters) if you're writing a generic method. + +TODO euler diagram \ No newline at end of file