Value types: define simple types #9215

pkulikov · 2018-11-24T18:08:01Z

While the char type is an integral type, I think it's still worth an explicit mention in the list of structs.

Other changes are minor style updates.

richlander · 2018-11-25T18:15:40Z

docs/csharp/language-reference/keywords/value-types.md

+
+ Structs fall into these categories:
+
+- Numeric types and [char](char.md)


I think it is odd to mention char twice, particularly in the title. "Numeric types and char" doesn't seem like a category to me. I'd stick with "Numeric types". Char is either a numeric type of not.

On the topic of numeric types, I am still not convinced that char is a numeric type. This is the best code I can write that makes me consider it as numeric.

char ten = (char)10; char twenty = (char)20; Console.WriteLine(ten * twenty);

The first two files rely on an explicit cast. If it was implicit, I'd feel more compelled. The thing that makes it numeric type is that it uses ints as both a backing data structure and it has a well-defined conversion with ints. So, to my mind, calling it numeric is more academic than practical.

I think that characterizing structs is difficult. Are ValueTask, Index, and Span in the user-defined structs category? If so, then I'd switch your categorization of structs to be: primitive, special , and user-defined. "special" is a bad name but I cannot think of something better ATM. Span is neither primitive or user-defined, in my mind. Another framing might be: provided (as in "in-box") and user-defined.

@richlander

I think that characterizing structs is difficult.

Definitely. Thanks a lot for your response. It made me look at the article more critically.

I think the struct categorization is not necessary at all here. How does it help to reason about value types? What I've noticed is that the current "categorization" is about simple types and all other structs, which are called user-defined structs (yes, even BigInteger becomes a user-defined struct). So, I've removed the categorization and, instead, provided the definition (through enumeration) of the simple types. Why is it necessary to have such a category: simple types? Because those differ from all other structs and those differences are then in the article.

I've updated the article based on the C# language spec and omitted the last "feature" of the simple types. Please let me know if you think that it should go to the docs as well.

richlander · 2018-11-25T19:05:47Z

docs/csharp/language-reference/keywords/value-types.md

- All of the simple types -- those integral to the C# language -- are aliases of the .NET Framework System types. For example, [int](../../../csharp/language-reference/keywords/int.md) is an alias of <xref:System.Int32?displayProperty=nameWithType>. For a complete list of aliases, see [Built-In Types Table](../../../csharp/language-reference/keywords/built-in-types-table.md).  
+## Main features of simple types
+
+ All of the simple types -- those integral to the C# language -- are aliases of the .NET <xref:System> types. For example, [int](int.md) is an alias of <xref:System.Int32?displayProperty=nameWithType>. For a complete list of aliases, see [Built-in types table](built-in-types-table.md).  


Here we have a different category "simple types". The categorization and this section should match.

We shouldn't use the word "integral". It is too close to integer, and there are better synonyms available.

I would remove the article in "are aliases of the .NET System types"

Please check new updates; I've updated this section a lot.

richlander · 2018-11-25T19:10:13Z

docs/csharp/language-reference/keywords/value-types.md

+ Using the [new](new.md) operator calls the default constructor of the specific type and assigns the default value to the variable. In the preceding example, the default constructor assigned the value `0` to `myInt`. For more information about values assigned by calling default constructors, see [Default values table](default-values-table.md).  

- With user-defined types, use [new](../../../csharp/language-reference/keywords/new.md) to invoke the default constructor. For example, the following statement invokes the default constructor of the `Point` struct:  
+ With user-defined types, use [new](new.md) to invoke the default constructor. For example, the following statement invokes the default constructor of the `Point` struct:  


Should new be in a code block?

As far as I observe and remember, code fencing is not applied in the link texts. though sometimes one can notice the link text with code fencing. @mairaw what is the rule here?

I agree. We shouldn't use code fencing for links (it looks strange), however, I think it is important for keywords to be code fenced. I noticed another usage where the first entry was code-fenced and then a later entry was linked. I found that to be the best model as a reader.

richlander · 2018-11-25T21:25:58Z

docs/csharp/language-reference/keywords/value-types.md

-## Main Features of Value Types  
+# Value types (C# Reference)
+
+The value types consist of two main categories:


I don't think a leading article is necessary here. How about:

There are two kinds of value types:

richlander · 2018-11-25T21:34:00Z

docs/csharp/language-reference/keywords/value-types.md

+
+## Main features of value types
+
 Variables that are based on value types directly contain values. Assigning one value type variable to another copies the contained value. This differs from the assignment of reference type variables, which copies a reference to the object but not the object itself.  


I am having trouble with the "variables that are based on" phrase. How about something like:

Variables in C# are declared or inferred to be a certain type. This type is is either a value or reference type. Variables that are a value type, like int, contain the value of the type, like 42. This differs from variables that are a reference type, like string, which contain a reference (the memory location) to a value (otherwise known as an "object").

Thanks for suggestion; I've reworked the paragraph.

richlander · 2018-11-25T21:43:34Z

I was looking at this text ...

Unlike reference types, a value type cannot contain the null value. However, the nullable types feature does allow for value types to be assigned to null.

It would be good to make nullability seem more integrated. I think it is written this way since nullability came later. When we write the nullable reference types docs, we'll want them written a similar way, I think.

How about:

Value type variables cannot be null by default. However, value type variables can be declared to be nullable, with the ? syntax, and can then hold the null value.

richlander · 2018-11-25T21:48:50Z

docs/csharp/language-reference/keywords/value-types.md

+ Each value type has an implicit default constructor that initializes the default value of that type. For information about default values of value types, see [Default values table](default-values-table.md).  

- Simple types can be initialized by using literals. For example, 'A' is a literal of the type `char` and 2001 is a literal of the type `int`.  
+## Simple types


It seems like all of the following text should go into the structs topic not the more general value types topic. All of this is specific to structs, right?

The "simple types" section seems to beg for a matching user-defined types section.

The "simple types" section seems to beg for a matching user-defined types section

What would such a section contain? Is there any property of user-defined structs that is not valid for a simple type?

It seems like all of the following text should go into the structs topic not the more general value types topic. All of this is specific to structs, right?

Though I agree with this, I don't think this PR should handle it. Simply because what is the structs topic? There are several candidates:

https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/struct

https://docs.microsoft.com/en-us/dotnet/csharp/structs

https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/structs

#966 is tracking the duplication issue.

What would such a section contain? Is there any property of user-defined structs that is not valid for a simple type?

There may not be differences. It's more that there is a section dedicated to one form of structs and not to the other.

Though I agree with this, I don't think this PR should handle it.

Sounds good.

It's more that there is a section dedicated to one form of structs and not to the other.

I see the whole picture as one set of structs (simple types) is a special subset of the set of all struct types. So, what should be described is (1) structs in general; (2) simple types. Though, it's good idea to say that a user-defined struct is a struct, which is not a simple type. I don't know where to put it yet in docs. So, come back to it later (together with another review of this topic, which can still be improved).

pkulikov · 2018-11-25T22:44:32Z

docs/csharp/language-reference/keywords/value-types.md

+
+## Main features of value types
+
+A variable of a value type contains a value of the type. For example, a variable of the `int` type might contain the value `42`. This differs from a variable of a reference type, which contains a reference to an instance of the type, also known as an object. When you assign a new value to a variable of a value type, that value is copied. When you assign a new value to a variable of a reference type, the reference is copied, not the object itself.


@richlander @BillWagner please check this one rigorously

richlander · 2018-11-25T23:16:10Z

LGTM. Thanks!

Value types: explicitly mention char

d8db3bc

pkulikov requested a review from BillWagner as a code owner November 24, 2018 18:08

More links simplified

69195a3

richlander reviewed Nov 25, 2018

View reviewed changes

pkulikov added 3 commits November 25, 2018 20:37

Rework struct categorization

1b3449e

Remove a line break

2255293

Added link to the C# spec

c6d9393

pkulikov changed the title ~~Value types: mention char~~ Value types: define simple types Nov 25, 2018

richlander reviewed Nov 25, 2018

View reviewed changes

Addressed feedback

f15fc4d

pkulikov commented Nov 25, 2018

View reviewed changes

richlander approved these changes Nov 25, 2018

View reviewed changes

BillWagner assigned pkulikov Nov 26, 2018

BillWagner added this to the Sprint 145 (11/26/2018 - 12/14/2018) milestone Nov 26, 2018

BillWagner merged commit ea0f28d into dotnet:master Nov 26, 2018

pkulikov deleted the patch-7 branch November 26, 2018 15:52


		Structs fall into these categories:

		- Numeric types and [char](char.md)


		## Main features of value types

		Variables that are based on value types directly contain values. Assigning one value type variable to another copies the contained value. This differs from the assignment of reference type variables, which copies a reference to the object but not the object itself.


		## Main features of value types

		A variable of a value type contains a value of the type. For example, a variable of the `int` type might contain the value `42`. This differs from a variable of a reference type, which contains a reference to an instance of the type, also known as an object. When you assign a new value to a variable of a value type, that value is copied. When you assign a new value to a variable of a reference type, the reference is copied, not the object itself.

Value types: define simple types #9215

Value types: define simple types #9215

Uh oh!

Conversation

pkulikov commented Nov 24, 2018

Uh oh!

richlander Nov 25, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

richlander commented Nov 25, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pkulikov Nov 26, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

richlander commented Nov 25, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

richlander Nov 25, 2018 •

edited

Loading

pkulikov Nov 26, 2018 •

edited

Loading