Skip to content

Commit ddf8ee0

Browse files
Guard APIs (#3131)
* Initial guard APIs added * Added EqualTo and NotEqualTo APIs * Added more Guard APIs * New interval Guard APIs added * Added Guard APIs for IEnumerable<T> values * Renamed APIs * Added Guard APIs for Stream values * Added Guard APIs for ReadOnlySpan<T> values * Added Guard APIs for ReadOnlyMemory<T> values * Code refactoring * Minor code refactoring * Added Guard.IsBitwiseEqualTo<T> API * Added Guard.IsNull API * Code refactoring and optimizations * Code refactoring * Added Guard.HasSizeNotEqualTo<T> API * Added Guard size API overloads for the string type * Added Guard size API overloads for T[] arrays * Code refactoring * Removed unnecessary using directives * Added Guard reference check APIs * Added new Guaard APIs for string values * Improved Guard.IsBitwiseEqualTo<T> API * Improved Guard.IsNull APIs * Added new size APIs for copy operations * Added new type test APIs, minor code tweaks * Minor bug fixes * Added Guard APIs for Task values * Minor code tweak * Added new Guard.IsEmpty APIs * Refactored code to remove unsafe requirement * Added Guard.IsInRange<T> APIs * Added missing type checks in Guard.IsBitwiseEqualTo API * Added ValueTypeExtensions.ToHexString API * Code refactoring * Added ValueTypeExtensions tests * Added general Guard tests * Bug fixes in the Guard class * Minor speed improvements * Code refactoring * Removed unnecessary using directives * More speed improvements and API refactoring * Refactored/fixed some Guard APIs * More bug fixes * Added Guard tests for array APIs * Fixed the Guard.IsNotEmpty<T> array API * Moved exception throwers to separate class * Moved general Guard throwers to separate class * Disabled warning for XML overload resolution * Moved array Guard throwers to separate class * Moved stream Guard throwers to separate class * Fixed some XML docs * Moved enumerable Guard throwers to separate class * Moved task Guard throwers to separate class * Added new Guard APIs for tasks * Moved string Guard throwers to separate class * Moved ReadOnlySpan<T> Guard throwers to separate class * Added Span<T> APIs to the Guard class * Moved ReadOnlyMemory<T> Guard throwers to separate class * Added Memory<T> APIs to the Guard class * Minor code refactoring * Update file headers * Removed unnecessary methods * Added TypeExtensions.ToTypeString extension * Improved error messages for general Guard APIs * Improved error messages for Enumerable Guard APIs * Improved error messages for stream Guard APIs * Improved error messages for array Guard APIs * Improved error messages for string Guard APIs * Improved error messages for task Guard APIs * Improved error messages for span Guard APIs * Improved error messages for memory Guard APIs * Improved type string for nullable types * Improved type string for value tuple types * Minor performance improvement * Added numeric comparison T4 file * Updated .gitignore to skip generated files * Moved comparison Guard APIs to separate file * Renamed template file, fixed incorrect XML doc * Fixed missing blank line * Removed unnecessary type parameters * Moved enumerable Guard APIs to separate file * Code refactoring in the enumerable T4 template * Renamed a file * Added empty template for ThrowHelper.Collection * Code refactoring in the T4 templates * Switched collection throw helpers to T4 generation * Code refactoring * Removed incorrect file header * Added new Guard.IsInRangeFor API * Updated .gitignore, added generated files to source control * Added tests for Guard.IsInRangeFor * Improved formatting of values in error messages * Improved error messages * More improvements to the error messages * Minor code tweaks * Added Guard.IsNotOfType APIs * Added Guard.IsNotAssignableToType APIs * Added Guard.IsDefault<T> APIs * Fixed some XML docs * Added missing [Pure] attribute * Fixed typo in a comment * Removed unnecessary comment after code changes * Added XML comment for the T4 service * Added more comments to ToHexString * Suppressed an incorrect code style warning * Added more tests for Guard.IsInRange * Added Guard.IsNotInRangeFor APIs * Added readme file for the T4 templates * Changed generated files extension to .g.cs to avoid conflicts * Added Guard.IsCloseTo and Guard.IsNotCloseTo APIs * Added tests for IsCloseTo * Updated ".g.cs" extension for generated files Co-Authored-By: Michael Hawker MSFT (XAML Llama) <[email protected]> * Removed extra space (typo) Co-Authored-By: Michael Hawker MSFT (XAML Llama) <[email protected]> * More tweakes to the Guard.md file * Excluded TypeInfo.g.cs file from .ttinclude from checkout * Added more info about target ranges for some APIs * Added IsCloseTo overloads for long type * Minor code tweaks * Added comment to describe (uint) cast range check trick * Added a nore about the .g.cs files being checked in * Fixed IsCloseTo tests * Fixed IsNull tests Co-authored-by: Michael Hawker MSFT (XAML Llama) <[email protected]>
1 parent da40efe commit ddf8ee0

35 files changed

+9316
-6
lines changed

.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -225,3 +225,6 @@ msbuild.binlog
225225
*.project.lock.json
226226
/build/tools/**
227227
!/build/tools/packages.config
228+
229+
# Generated file from .ttinclude
230+
**/Generated/TypeInfo.g.cs

Microsoft.Toolkit/Converters.cs

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,6 @@
22
// The .NET Foundation licenses this file to you under the MIT license.
33
// See the LICENSE file in the project root for more information.
44

5-
using System;
6-
using System.Collections.Generic;
7-
using System.Text;
8-
95
namespace Microsoft.Toolkit
106
{
117
/// <summary>

Microsoft.Toolkit/Diagnostics/Generated/Guard.Collection.g.cs

Lines changed: 1638 additions & 0 deletions
Large diffs are not rendered by default.
Lines changed: 283 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,283 @@
1+
// Licensed to the .NET Foundation under one or more agreements.
2+
// The .NET Foundation licenses this file to you under the MIT license.
3+
// See the LICENSE file in the project root for more information.
4+
<#@include file="TypeInfo.ttinclude" #>
5+
/* ========================
6+
* Auto generated file
7+
* ===================== */
8+
9+
using System;
10+
using System.Collections.Generic;
11+
using System.Runtime.CompilerServices;
12+
13+
#nullable enable
14+
15+
namespace Microsoft.Toolkit.Diagnostics
16+
{
17+
/// <summary>
18+
/// Helper methods to verify conditions when running code.
19+
/// </summary>
20+
public static partial class Guard
21+
{
22+
<#
23+
GenerateTextForItems(EnumerableTypes, item =>
24+
{
25+
#>
26+
/// <summary>
27+
/// Asserts that the input <#=item.XmlType#> instance must be empty.
28+
/// </summary>
29+
/// <typeparam name="T">The item of items in the input <#=item.XmlType#> instance.</typeparam>
30+
/// <param name="<#=item.Name#>">The input <#=item.XmlType#> instance to check the size for.</param>
31+
/// <param name="name">The name of the input parameter being tested.</param>
32+
/// <exception cref="ArgumentException">Thrown if the size of <paramref name="<#=item.Name#>"/> is != 0.</exception>
33+
[MethodImpl(MethodImplOptions.AggressiveInlining)]
34+
public static void IsEmpty<T>(<#=item.Type#> <#=item.Name#>, string name)
35+
{
36+
if (<#=item.Name#>.<#=item.Size#> != 0)
37+
{
38+
ThrowHelper.ThrowArgumentExceptionForIsEmpty(<#=item.Cast#><#=item.Name#>, name);
39+
}
40+
}
41+
42+
/// <summary>
43+
/// Asserts that the input <#=item.XmlType#> instance must not be empty.
44+
/// </summary>
45+
/// <typeparam name="T">The item of items in the input <#=item.XmlType#> instance.</typeparam>
46+
/// <param name="<#=item.Name#>">The input <#=item.XmlType#> instance to check the size for.</param>
47+
/// <param name="name">The name of the input parameter being tested.</param>
48+
/// <exception cref="ArgumentException">Thrown if the size of <paramref name="<#=item.Name#>"/> is == 0.</exception>
49+
[MethodImpl(MethodImplOptions.AggressiveInlining)]
50+
public static void IsNotEmpty<T>(<#=item.Type#> <#=item.Name#>, string name)
51+
{
52+
if (<#=item.Name#>.<#=item.Size#> == 0)
53+
{
54+
<#
55+
if (item.Type == "Span<T>")
56+
{
57+
#>
58+
ThrowHelper.ThrowArgumentExceptionForIsNotEmptyWithSpan<T>(name);
59+
<#
60+
}
61+
else if (item.Type == "ReadOnlySpan<T>")
62+
{
63+
#>
64+
ThrowHelper.ThrowArgumentExceptionForIsNotEmptyWithReadOnlySpan<T>(name);
65+
<#
66+
}
67+
else
68+
{
69+
#>
70+
ThrowHelper.ThrowArgumentExceptionForIsNotEmpty<<#=item.Type#>>(name);
71+
<#
72+
}
73+
#>
74+
}
75+
}
76+
77+
/// <summary>
78+
/// Asserts that the input <#=item.XmlType#> instance must have a size of a specified value.
79+
/// </summary>
80+
/// <typeparam name="T">The item of items in the input <#=item.XmlType#> instance.</typeparam>
81+
/// <param name="<#=item.Name#>">The input <#=item.XmlType#> instance to check the size for.</param>
82+
/// <param name="size">The target size to test.</param>
83+
/// <param name="name">The name of the input parameter being tested.</param>
84+
/// <exception cref="ArgumentException">Thrown if the size of <paramref name="<#=item.Name#>"/> is != <paramref name="size"/>.</exception>
85+
[MethodImpl(MethodImplOptions.AggressiveInlining)]
86+
public static void HasSizeEqualTo<T>(<#=item.Type#> <#=item.Name#>, int size, string name)
87+
{
88+
if (<#=item.Name#>.<#=item.Size#> != size)
89+
{
90+
ThrowHelper.ThrowArgumentExceptionForHasSizeEqualTo(<#=item.Cast#><#=item.Name#>, size, name);
91+
}
92+
}
93+
94+
/// <summary>
95+
/// Asserts that the input <#=item.XmlType#> instance must have a size not equal to a specified value.
96+
/// </summary>
97+
/// <typeparam name="T">The item of items in the input <#=item.XmlType#> instance.</typeparam>
98+
/// <param name="<#=item.Name#>">The input <#=item.XmlType#> instance to check the size for.</param>
99+
/// <param name="size">The target size to test.</param>
100+
/// <param name="name">The name of the input parameter being tested.</param>
101+
/// <exception cref="ArgumentException">Thrown if the size of <paramref name="<#=item.Name#>"/> is == <paramref name="size"/>.</exception>
102+
[MethodImpl(MethodImplOptions.AggressiveInlining)]
103+
public static void HasSizeNotEqualTo<T>(<#=item.Type#> <#=item.Name#>, int size, string name)
104+
{
105+
if (<#=item.Name#>.<#=item.Size#> == size)
106+
{
107+
ThrowHelper.ThrowArgumentExceptionForHasSizeNotEqualTo(<#=item.Cast#><#=item.Name#>, size, name);
108+
}
109+
}
110+
111+
/// <summary>
112+
/// Asserts that the input <#=item.XmlType#> instance must have a size over a specified value.
113+
/// </summary>
114+
/// <typeparam name="T">The item of items in the input <#=item.XmlType#> instance.</typeparam>
115+
/// <param name="<#=item.Name#>">The input <#=item.XmlType#> instance to check the size for.</param>
116+
/// <param name="size">The target size to test.</param>
117+
/// <param name="name">The name of the input parameter being tested.</param>
118+
/// <exception cref="ArgumentException">Thrown if the size of <paramref name="<#=item.Name#>"/> is &lt;= <paramref name="size"/>.</exception>
119+
[MethodImpl(MethodImplOptions.AggressiveInlining)]
120+
public static void HasSizeOver<T>(<#=item.Type#> <#=item.Name#>, int size, string name)
121+
{
122+
if (<#=item.Name#>.<#=item.Size#> <= size)
123+
{
124+
ThrowHelper.ThrowArgumentExceptionForHasSizeOver(<#=item.Cast#><#=item.Name#>, size, name);
125+
}
126+
}
127+
128+
/// <summary>
129+
/// Asserts that the input <#=item.XmlType#> instance must have a size of at least or equal to a specified value.
130+
/// </summary>
131+
/// <typeparam name="T">The item of items in the input <#=item.XmlType#> instance.</typeparam>
132+
/// <param name="<#=item.Name#>">The input <#=item.XmlType#> instance to check the size for.</param>
133+
/// <param name="size">The target size to test.</param>
134+
/// <param name="name">The name of the input parameter being tested.</param>
135+
/// <exception cref="ArgumentException">Thrown if the size of <paramref name="<#=item.Name#>"/> is &lt; <paramref name="size"/>.</exception>
136+
[MethodImpl(MethodImplOptions.AggressiveInlining)]
137+
public static void HasSizeAtLeast<T>(<#=item.Type#> <#=item.Name#>, int size, string name)
138+
{
139+
if (<#=item.Name#>.<#=item.Size#> < size)
140+
{
141+
ThrowHelper.ThrowArgumentExceptionForHasSizeAtLeast(<#=item.Cast#><#=item.Name#>, size, name);
142+
}
143+
}
144+
145+
/// <summary>
146+
/// Asserts that the input <#=item.XmlType#> instance must have a size of less than a specified value.
147+
/// </summary>
148+
/// <typeparam name="T">The item of items in the input <#=item.XmlType#> instance.</typeparam>
149+
/// <param name="<#=item.Name#>">The input <#=item.XmlType#> instance to check the size for.</param>
150+
/// <param name="size">The target size to test.</param>
151+
/// <param name="name">The name of the input parameter being tested.</param>
152+
/// <exception cref="ArgumentException">Thrown if the size of <paramref name="<#=item.Name#>"/> is >= <paramref name="size"/>.</exception>
153+
[MethodImpl(MethodImplOptions.AggressiveInlining)]
154+
public static void HasSizeLessThan<T>(<#=item.Type#> <#=item.Name#>, int size, string name)
155+
{
156+
if (<#=item.Name#>.<#=item.Size#> >= size)
157+
{
158+
ThrowHelper.ThrowArgumentExceptionForHasSizeLessThan(<#=item.Cast#><#=item.Name#>, size, name);
159+
}
160+
}
161+
162+
/// <summary>
163+
/// Asserts that the input <#=item.XmlType#> instance must have a size of less than or equal to a specified value.
164+
/// </summary>
165+
/// <typeparam name="T">The item of items in the input <#=item.XmlType#> instance.</typeparam>
166+
/// <param name="<#=item.Name#>">The input <#=item.XmlType#> instance to check the size for.</param>
167+
/// <param name="size">The target size to test.</param>
168+
/// <param name="name">The name of the input parameter being tested.</param>
169+
/// <exception cref="ArgumentException">Thrown if the size of <paramref name="<#=item.Name#>"/> is > <paramref name="size"/>.</exception>
170+
[MethodImpl(MethodImplOptions.AggressiveInlining)]
171+
public static void HasSizeLessThanOrEqualTo<T>(<#=item.Type#> <#=item.Name#>, int size, string name)
172+
{
173+
if (<#=item.Name#>.<#=item.Size#> > size)
174+
{
175+
ThrowHelper.ThrowArgumentExceptionForHasSizeLessThanOrEqualTo(<#=item.Cast#><#=item.Name#>, size, name);
176+
}
177+
}
178+
179+
/// <summary>
180+
/// Asserts that the source <#=item.XmlType#> instance must have the same size of a destination <#=item.XmlType#> instance.
181+
/// </summary>
182+
/// <typeparam name="T">The item of items in the input <#=item.XmlType#> instance.</typeparam>
183+
/// <param name="source">The source <#=item.XmlType#> instance to check the size for.</param>
184+
/// <param name="destination">The destination <#=item.XmlType#> instance to check the size for.</param>
185+
/// <param name="name">The name of the input parameter being tested.</param>
186+
/// <exception cref="ArgumentException">Thrown if the size of <paramref name="source"/> is != the one of <paramref name="destination"/>.</exception>
187+
[MethodImpl(MethodImplOptions.AggressiveInlining)]
188+
public static void HasSizeEqualTo<T>(<#=item.Type#> source, <#=item.DestinationType#> destination, string name)
189+
{
190+
if (source.<#=item.Size#> != destination.<#=item.Size#>)
191+
{
192+
<#
193+
if (item.HasCountProperty)
194+
{
195+
#>
196+
ThrowHelper.ThrowArgumentExceptionForHasSizeEqualTo(<#=item.Cast#>source, destination.<#=item.Size#>, name);
197+
<#
198+
}
199+
else
200+
{
201+
#>
202+
ThrowHelper.ThrowArgumentExceptionForHasSizeEqualTo(source, <#=item.Cast#>destination, name);
203+
<#
204+
}
205+
#>
206+
}
207+
}
208+
209+
/// <summary>
210+
/// Asserts that the source <#=item.XmlType#> instance must have a size of less than or equal to that of a destination <#=item.XmlType#> instance.
211+
/// </summary>
212+
/// <typeparam name="T">The item of items in the input <#=item.XmlType#> instance.</typeparam>
213+
/// <param name="source">The source <#=item.XmlType#> instance to check the size for.</param>
214+
/// <param name="destination">The destination <#=item.XmlType#> instance to check the size for.</param>
215+
/// <param name="name">The name of the input parameter being tested.</param>
216+
/// <exception cref="ArgumentException">Thrown if the size of <paramref name="source"/> is > the one of <paramref name="destination"/>.</exception>
217+
[MethodImpl(MethodImplOptions.AggressiveInlining)]
218+
public static void HasSizeLessThanOrEqualTo<T>(<#=item.Type#> source, <#=item.DestinationType#> destination, string name)
219+
{
220+
if (source.<#=item.Size#> > destination.<#=item.Size#>)
221+
{
222+
<#
223+
if (item.HasCountProperty)
224+
{
225+
#>
226+
ThrowHelper.ThrowArgumentExceptionForHasSizeEqualTo(<#=item.Cast#>source, destination.<#=item.Size#>, name);
227+
<#
228+
}
229+
else
230+
{
231+
#>
232+
ThrowHelper.ThrowArgumentExceptionForHasSizeLessThanOrEqualTo(source, <#=item.Cast#>destination, name);
233+
<#
234+
}
235+
#>
236+
}
237+
}
238+
239+
/// <summary>
240+
/// Asserts that the input index is valid for a given <#=item.XmlType#> instance.
241+
/// </summary>
242+
/// <typeparam name="T">The item of items in the input <#=item.XmlType#> instance.</typeparam>
243+
/// <param name="index">The input index to be used to access <paramref name="<#=item.Name#>"/>.</param>
244+
/// <param name="<#=item.Name#>">The input <#=item.XmlType#> instance to use to validate <paramref name="index"/>.</param>
245+
/// <param name="name">The name of the input parameter being tested.</param>
246+
/// <exception cref="ArgumentOutOfRangeException">Thrown if <paramref name="index"/> is not valid to access <paramref name="<#=item.Name#>"/>.</exception>
247+
[MethodImpl(MethodImplOptions.AggressiveInlining)]
248+
public static void IsInRangeFor<T>(int index, <#=item.Type#> <#=item.Name#>, string name)
249+
{
250+
<#
251+
/* Here we're leveraging the fact that signed integers are represented
252+
* in 2-complement to perform the bounds check with a single compare operation.
253+
* This is the same trick used throughout CoreCLR as well.
254+
* For more info and code sample, see the original conversation here:
255+
* https://github.com/windows-toolkit/WindowsCommunityToolkit/pull/3131#discussion_r390682835 */
256+
#>
257+
if ((uint)index >= (uint)<#=item.Name#>.<#=item.Size#>)
258+
{
259+
ThrowHelper.ThrowArgumentOutOfRangeExceptionForIsInRangeFor(index, <#=item.Cast#><#=item.Name#>, name);
260+
}
261+
}
262+
263+
/// <summary>
264+
/// Asserts that the input index is not valid for a given <#=item.XmlType#> instance.
265+
/// </summary>
266+
/// <typeparam name="T">The item of items in the input <#=item.XmlType#> instance.</typeparam>
267+
/// <param name="index">The input index to be used to access <paramref name="<#=item.Name#>"/>.</param>
268+
/// <param name="<#=item.Name#>">The input <#=item.XmlType#> instance to use to validate <paramref name="index"/>.</param>
269+
/// <param name="name">The name of the input parameter being tested.</param>
270+
/// <exception cref="ArgumentOutOfRangeException">Thrown if <paramref name="index"/> is valid to access <paramref name="<#=item.Name#>"/>.</exception>
271+
[MethodImpl(MethodImplOptions.AggressiveInlining)]
272+
public static void IsNotInRangeFor<T>(int index, <#=item.Type#> <#=item.Name#>, string name)
273+
{
274+
if ((uint)index < (uint)<#=item.Name#>.<#=item.Size#>)
275+
{
276+
ThrowHelper.ThrowArgumentOutOfRangeExceptionForIsNotInRangeFor(index, <#=item.Cast#><#=item.Name#>, name);
277+
}
278+
}
279+
<#
280+
});
281+
#>
282+
}
283+
}

0 commit comments

Comments
 (0)