Skip to content

Commit 4197154

Browse files
carlossanlopRon Petrusha
carlossanlop
authored and
Ron Petrusha
committed
Document System.Guid (#3251)
* Document System.Guid * suggestions by rpetrusha Co-Authored-By: Ron Petrusha <[email protected]> * delete unrelated example * delete unrelated example
1 parent ea372c7 commit 4197154

File tree

1 file changed

+151
-42
lines changed

1 file changed

+151
-42
lines changed

‎xml/System/Guid.xml

Lines changed: 151 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -152,9 +152,10 @@
152152
<Parameter Name="b" Type="System.ReadOnlySpan&lt;System.Byte&gt;" Index="0" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
153153
</Parameters>
154154
<Docs>
155-
<param name="b">To be added.</param>
156-
<summary>To be added.</summary>
155+
<param name="b">A read-only span containing the bytes representing the GUID. The span must be exactly 16 bytes long.</param>
156+
<summary>Initializes a new instance of the <see cref="T:System.Guid" /> structure by using the value represented by the specified read-only span of bytes.</summary>
157157
<remarks>To be added.</remarks>
158+
<exception cref="T:System.ArgumentException">The span must be exactly 16 bytes long.</exception>
158159
</Docs>
159160
</Member>
160161
<Member MemberName=".ctor">
@@ -1039,10 +1040,44 @@
10391040
<Parameter Name="input" Type="System.ReadOnlySpan&lt;System.Char&gt;" Index="0" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
10401041
</Parameters>
10411042
<Docs>
1042-
<param name="input">To be added.</param>
1043-
<summary>To be added.</summary>
1044-
<returns>To be added.</returns>
1045-
<remarks>To be added.</remarks>
1043+
<param name="input">A read-only span containing the bytes representing a GUID.</param>
1044+
<summary>Converts a read-only character span that represents a GUID to the equivalent <see cref="T:System.Guid" /> structure.</summary>
1045+
<returns>A structure that contains the value that was parsed.</returns>
1046+
<remarks>
1047+
<format type="text/markdown"><![CDATA[
1048+
1049+
## Remarks
1050+
1051+
The <xref:System.Guid.Parse%2A> method trims any leading or trailing white space characters from `input` and converts the remaining characters in `input` to a <xref:System.Guid> value. This method can convert a character span that represents any of the five formats produced by the <xref:System.Guid.ToString%2A> methods, as shown in the following table.
1052+
1053+
|Specifier|Description|Format|
1054+
|---------------|-----------------|------------|
1055+
|`N`|32 digits|00000000000000000000000000000000|
1056+
|`D`|32 digits separated by hyphens|00000000-0000-0000-0000-000000000000|
1057+
|`B`|32 digits separated by hyphens, enclosed in braces|{00000000-0000-0000-0000-000000000000}|
1058+
|`P`|32 digits separated by hyphens, enclosed in parentheses|(00000000-0000-0000-0000-000000000000)|
1059+
|`X`|Four hexadecimal values enclosed in braces, where the fourth value is a subset of eight hexadecimal values that is also enclosed in braces|{0x00000000,0x0000,0x0000,{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}}|
1060+
1061+
The method throws a <xref:System.FormatException> if it is unable to successfully parse the string. Here are some of the reasons why this might occur include:
1062+
1063+
- `input` contains characters that are not part of the hexadecimal character set.
1064+
1065+
- `input` has too many or too few numeric characters.
1066+
1067+
- `input` has too many or too few of the non-numeric characters appropriate for a particular format.
1068+
1069+
- `input` is not in one of the formats recognized by the <xref:System.Guid.ToString%2A> method and listed in the previous table.
1070+
1071+
Use the <xref:System.Guid.TryParse%2A> method to catch any unsuccessful parse operations without having to handle an exception.
1072+
1073+
]]></format>
1074+
</remarks>
1075+
<exception cref="T:System.FormatException"><paramref name="input" /> is not in a recognized format.
1076+
1077+
-or-
1078+
1079+
After trimming, the length of the read-only character span is 0.
1080+
</exception>
10461081
</Docs>
10471082
</Member>
10481083
<Member MemberName="Parse">
@@ -1118,10 +1153,8 @@
11181153
11191154
]]></format>
11201155
</remarks>
1121-
<exception cref="T:System.ArgumentNullException">
1122-
<paramref name="input" /> is <see langword="null" />.</exception>
1123-
<exception cref="T:System.FormatException">
1124-
<paramref name="input" /> is not in a recognized format.</exception>
1156+
<exception cref="T:System.ArgumentNullException"><paramref name="input" /> is <see langword="null" />.</exception>
1157+
<exception cref="T:System.FormatException"><paramref name="input" /> is not in a recognized format.</exception>
11251158
<altmember cref="M:System.Guid.TryParse(System.String,System.Guid@)" />
11261159
<altmember cref="M:System.Guid.ToString" />
11271160
</Docs>
@@ -1153,11 +1186,27 @@
11531186
<Parameter Name="format" Type="System.ReadOnlySpan&lt;System.Char&gt;" Index="1" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
11541187
</Parameters>
11551188
<Docs>
1156-
<param name="input">To be added.</param>
1157-
<param name="format">To be added.</param>
1158-
<summary>To be added.</summary>
1159-
<returns>To be added.</returns>
1160-
<remarks>To be added.</remarks>
1189+
<param name="input">A read-only span containing the characters representing the GUID to convert.</param>
1190+
<param name="format">A read-only span of characters representing one of the following specifiers that indicates the exact format to use when interpreting <paramref name="input" />: "N", "D", "B", "P", or "X".</param>
1191+
<summary>Converts the character span representation of a GUID to the equivalent <see cref="T:System.Guid" /> structure, provided that the string is in the specified format.</summary>
1192+
<returns>A structure that contains the value that was parsed.</returns>
1193+
<remarks>
1194+
<format type="text/markdown"><![CDATA[
1195+
1196+
## Remarks
1197+
1198+
The <xref:System.Guid.ParseExact%2A> method requires the read-only character span to convert to be exactly in the format specified by the `format` parameter, after leading and trailing white-space characters are removed. The following table shows the accepted format specifiers for the `format` parameter. "0" represents a digit; hyphens ("-"), braces ("{", "}"), and parentheses ("(", ")") appear as shown.
1199+
1200+
|Specifier|Format of the `input` parameter|
1201+
|---------------|-------------------------------------|
1202+
|N|32 digits:<br /><br /> 00000000000000000000000000000000|
1203+
|D|32 digits separated by hyphens:<br /><br /> 00000000-0000-0000-0000-000000000000|
1204+
|B|32 digits separated by hyphens, enclosed in braces:<br /><br /> {00000000-0000-0000-0000-000000000000}|
1205+
|P|32 digits separated by hyphens, enclosed in parentheses:<br /><br /> (00000000-0000-0000-0000-000000000000)|
1206+
|X|Four hexadecimal values enclosed in braces, where the fourth value is a subset of eight hexadecimal values that is also enclosed in braces:<br /><br /> {0x00000000,0x0000,0x0000,{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}}|
1207+
1208+
]]></format>
1209+
</remarks>
11611210
</Docs>
11621211
</Member>
11631212
<Member MemberName="ParseExact">
@@ -1260,10 +1309,50 @@
12601309
<Parameter Name="value" Type="System.Object" Index="0" FrameworkAlternate="dotnet-uwp-10.0;netcore-1.0;netcore-1.1;netstandard-1.0;netstandard-1.1;netstandard-1.2;netstandard-1.3;netstandard-1.4;netstandard-1.5;netstandard-1.6" />
12611310
</Parameters>
12621311
<Docs>
1263-
<param name="value">To be added.</param>
1264-
<summary>To be added.</summary>
1265-
<returns>To be added.</returns>
1266-
<remarks>To be added.</remarks>
1312+
<param name="value">An object to compare to this instance.</param>
1313+
<summary>Compares this instance to a specified <see cref="T:System.Guid" /> object and returns an indication of their relative values.</summary>
1314+
<returns>A signed number indicating the relative values of this instance and <paramref name="value" />.
1315+
<list type="table">
1316+
<listheader>
1317+
<term>Return value</term>
1318+
<description>Description</description>
1319+
</listheader>
1320+
<item>
1321+
<term>A negative integer</term>
1322+
<description>This instance is less than <paramref name="value" />.</description>
1323+
</item>
1324+
<item>
1325+
<term>Zero</term>
1326+
<description>This instance is equal to <paramref name="value" />.</description>
1327+
</item>
1328+
<item>
1329+
<term>A positive integer</term>
1330+
<description>This instance is greater than <paramref name="value" />.</description>
1331+
</item>
1332+
</list>
1333+
</returns>
1334+
<remarks>
1335+
<format type="text/markdown"><![CDATA[
1336+
1337+
## Remarks
1338+
1339+
This member is an explicit interface member implementation. It can only be used when the <xref:System.Guid" /> instance is cast to an <xref:System.IComparable> interface.
1340+
1341+
The `CompareTo` method compares the GUIDs as if they were values provided to the <xref:System.Guid.%23ctor%28System.Int32%2CSystem.Int16%2CSystem.Int16%2CSystem.Byte%5B%5D%29> constructor, as follows:
1342+
1343+
- It compares the <xref:System.UInt32> values, and returns a result if they are unequal. If they are equal, it performs the next comparison.
1344+
- It compares the first <xref:System.UInt16> values, and returns a result if they are unequal. If they are equal, it performs the next comparison.
1345+
- It compares the second <xref:System.UInt16> values, and returns a result if they are unequal. If they are equal, it performs the next comparison.
1346+
- If performs a byte-by-byte comparison of the next eight <xref:System.Byte> values. When it encounters the first unequal pair, it returns the result. Otherwise, it returns 0 to indicate that the two <xref:System.Guid> values are equal.
1347+
1348+
Note that the final eight bytes appear in the string representation of a <xref:System.Guid> in reverse order, from low byte to high byte. For example, in the string representation of the <xref:System.Guid> value "01e75c83-c6f5-4192-b57e-7427cec5560d", the final eight bytes are "b57e-7427cec5560d." In other words, the final eight bytes are compared on a byte-by-byte basis from left to right starting with 0xb5.
1349+
1350+
If two GUIDs have equal values for a component, the method compares the next component. When it finds a component whose values are unequal, it returns the result.
1351+
1352+
This method implements the <xref:System.IComparable%601?displayProperty=nameWithType> interface and performs slightly better than the <xref:System.Guid.CompareTo%2A?displayProperty=nameWithType> method because it does not have to convert the `value` parameter to a <xref:System.Guid> value.
1353+
1354+
]]></format>
1355+
</remarks>
12671356
</Docs>
12681357
</Member>
12691358
<Member MemberName="System.IFormattable.ToString">
@@ -1298,10 +1387,32 @@
12981387
</Parameters>
12991388
<Docs>
13001389
<param name="format">A single format specifier that indicates how to format the value of the <see cref="T:System.Guid" />. The <paramref name="format" /> parameter can be "N", "D", "B", "P", or "X". If <paramref name="format" /> is null or an empty string (""), "D" is used.</param>
1301-
<param name="provider">To be added.</param>
1390+
<param name="provider">(Reserved) An object that supplies culture-specific formatting information.</param>
13021391
<summary>Returns a string representation of the value of this instance, according to the provided format specifier and culture-specific format information.</summary>
13031392
<returns>The value of this <see cref="T:System.Guid" /> represented as a series of lowercase hexadecimal digits in the specified format.</returns>
1304-
<remarks>To be added.</remarks>
1393+
<remarks>
1394+
<format type="text/markdown"><![CDATA[
1395+
1396+
## Remarks
1397+
1398+
The `provider` parameter is reserved for future use and does not contribute to the execution of this method. You can pass `null` in the method call.
1399+
1400+
The following table shows the accepted format specifiers for the `format` parameter. "0" represents a digit; hyphens ("-"), braces ("{", "}"), and parentheses ("(", ")") appear as shown.
1401+
1402+
|Specifier|Format of return value|
1403+
|---------------|----------------------------|
1404+
|`N`|32 digits:<br /><br /> 00000000000000000000000000000000|
1405+
|`D`|32 digits separated by hyphens:<br /><br /> 00000000-0000-0000-0000-000000000000|
1406+
|`B`|32 digits separated by hyphens, enclosed in braces:<br /><br /> {00000000-0000-0000-0000-000000000000}|
1407+
|`P`|32 digits separated by hyphens, enclosed in parentheses:<br /><br /> (00000000-0000-0000-0000-000000000000)|
1408+
|`X`|Four hexadecimal values enclosed in braces, where the fourth value is a subset of eight hexadecimal values that is also enclosed in braces:<br /><br /> {0x00000000,0x0000,0x0000,{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00}}|
1409+
1410+
The hexadecimal digits a through f are lowercase in the returned string. To convert them to uppercase, call the <xref:System.String.ToUpper%2A?displayProperty=nameWithType> method on the returned string.
1411+
1412+
Because the `provider` parameter is ignored, you cannot use it to provide a custom formatting solution. To represent a <xref:System.Guid> value as a string in a format that isn't supported by the standard GUID format strings, call the <xref:System.String.Format%28System.IFormatProvider%2CSystem.String%2CSystem.Object%5B%5D%29?displayProperty=nameWithType> method with a `provider` object that implements both the <xref:System.ICustomFormatter> and <xref:System.IFormatProvider> interfaces. For more information, see the ["Custom Formatting with ICustomFormatter"](~/docs/standard/base-types/formatting-types.md#custom-formatting-with-icustomformatter) section in the [Formatting Types](~/docs/standard/base-types/formatting-types.md) article.
1413+
1414+
]]></format>
1415+
</remarks>
13051416
<exception cref="T:System.FormatException">The value of <paramref name="format" /> is not null, an empty string (""), or one of the following single format specifiers:"N", "D", "B", "P", or "X".</exception>
13061417
</Docs>
13071418
</Member>
@@ -1581,11 +1692,11 @@
15811692
<Parameter Name="format" Type="System.ReadOnlySpan&lt;System.Char&gt;" Index="2" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
15821693
</Parameters>
15831694
<Docs>
1584-
<param name="destination">To be added.</param>
1585-
<param name="charsWritten">To be added.</param>
1586-
<param name="format">To be added.</param>
1587-
<summary>To be added.</summary>
1588-
<returns>To be added.</returns>
1695+
<param name="destination">When this method returns, the GUID as a span of characters.</param>
1696+
<param name="charsWritten">When this method returns, the number of characters written into the span.</param>
1697+
<param name="format">A read-only span containing the character representing one of the following specifiers that indicates the exact format to use when interpreting <paramref name="input" />: "N", "D", "B", "P", or "X".</param>
1698+
<summary>Tries to format the current GUID instance into the provided character span.</summary>
1699+
<returns><see langword="true" /> if the formatting operation was successful; <see langword="false" /> otherwise.</returns>
15891700
<remarks>To be added.</remarks>
15901701
</Docs>
15911702
</Member>
@@ -1616,10 +1727,10 @@
16161727
<Parameter Name="result" Type="System.Guid" RefType="out" Index="1" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
16171728
</Parameters>
16181729
<Docs>
1619-
<param name="input">To be added.</param>
1620-
<param name="result">To be added.</param>
1621-
<summary>To be added.</summary>
1622-
<returns>To be added.</returns>
1730+
<param name="input">A span containing the characters representing GUID to convert.</param>
1731+
<param name="result">The structure to contain the parsed value. If the method returns <see langword="true" />, <paramref name="result" /> contains a valid <see cref="T:System.Guid" />. If the method returns <see langword="false" />, <paramref name="result" /> equals <see cref="F:System.Guid.Empty" />.</param>
1732+
<summary>Converts the specified read-only span of characters containing the representation of a GUID to the equivalent <see cref="T:System.Guid" /> structure.</summary>
1733+
<returns><see langword="true" /> if the parse operation was successful; otherwise, <see langword="false" />.</returns>
16231734
<remarks>To be added.</remarks>
16241735
</Docs>
16251736
</Member>
@@ -1661,8 +1772,7 @@
16611772
<param name="input">The GUID to convert.</param>
16621773
<param name="result">The structure that will contain the parsed value. If the method returns <see langword="true" />, <paramref name="result" /> contains a valid <see cref="T:System.Guid" />. If the method returns <see langword="false" />, <paramref name="result" /> equals <see cref="F:System.Guid.Empty" />.</param>
16631774
<summary>Converts the string representation of a GUID to the equivalent <see cref="T:System.Guid" /> structure.</summary>
1664-
<returns>
1665-
<see langword="true" /> if the parse operation was successful; otherwise, <see langword="false" />.</returns>
1775+
<returns><see langword="true" /> if the parse operation was successful; otherwise, <see langword="false" />.</returns>
16661776
<remarks>
16671777
<format type="text/markdown"><![CDATA[
16681778
@@ -1718,11 +1828,11 @@
17181828
<Parameter Name="result" Type="System.Guid" RefType="out" Index="2" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
17191829
</Parameters>
17201830
<Docs>
1721-
<param name="input">To be added.</param>
1722-
<param name="format">To be added.</param>
1723-
<param name="result">To be added.</param>
1724-
<summary>To be added.</summary>
1725-
<returns>To be added.</returns>
1831+
<param name="input">A read-only span containing the characters representing the GUID to convert.</param>
1832+
<param name="format">A read-only span containing a character representing one of the following specifiers that indicates the exact format to use when interpreting <paramref name="input" />: "N", "D", "B", "P", or "X".</param>
1833+
<param name="result">The structure to contain the parsed value. If the method returns <see langword="true" />, <paramref name="result" /> contains a valid <see cref="T:System.Guid" />. If the method returns <see langword="false" />, <paramref name="result" /> equals <see cref="F:System.Guid.Empty" />.</param>
1834+
<summary>Converts span of characters representing the GUID to the equivalent <see cref="T:System.Guid" /> structure, provided that the string is in the specified format.</summary>
1835+
<returns><see langword="true" /> if the parse operation was successful; otherwise, <see langword="false" />.</returns>
17261836
<remarks>To be added.</remarks>
17271837
</Docs>
17281838
</Member>
@@ -1766,8 +1876,7 @@
17661876
<param name="format">One of the following specifiers that indicates the exact format to use when interpreting <paramref name="input" />: "N", "D", "B", "P", or "X".</param>
17671877
<param name="result">The structure that will contain the parsed value. If the method returns <see langword="true" />, <paramref name="result" /> contains a valid <see cref="T:System.Guid" />. If the method returns <see langword="false" />, <paramref name="result" /> equals <see cref="F:System.Guid.Empty" />.</param>
17681878
<summary>Converts the string representation of a GUID to the equivalent <see cref="T:System.Guid" /> structure, provided that the string is in the specified format.</summary>
1769-
<returns>
1770-
<see langword="true" /> if the parse operation was successful; otherwise, <see langword="false" />.</returns>
1879+
<returns><see langword="true" /> if the parse operation was successful; otherwise, <see langword="false" />.</returns>
17711880
<remarks>
17721881
<format type="text/markdown"><![CDATA[
17731882
@@ -1823,9 +1932,9 @@
18231932
<Parameter Name="destination" Type="System.Span&lt;System.Byte&gt;" Index="0" FrameworkAlternate="netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
18241933
</Parameters>
18251934
<Docs>
1826-
<param name="destination">To be added.</param>
1827-
<summary>To be added.</summary>
1828-
<returns>To be added.</returns>
1935+
<param name="destination">When this method returns, the GUID as a span of bytes.</param>
1936+
<summary>Tries to write the current GUID instance into a span of bytes.</summary>
1937+
<returns><see langword="true" /> if the GUID is sucessfully written to the specified span; <see langword="false" /> otherwise.</returns>
18291938
<remarks>To be added.</remarks>
18301939
</Docs>
18311940
</Member>

0 commit comments

Comments
 (0)