From ab6cf45b03073f324c46f9e93a98e3342a1bdff7 Mon Sep 17 00:00:00 2001 From: Jesse Plamondon-Willard Date: Thu, 7 Apr 2022 00:56:00 -0400 Subject: enable nullable annotations for semantic versions (#837) --- src/SMAPI.Tests/Utilities/SemanticVersionTests.cs | 35 ++++++------- .../ISemanticVersion.cs | 38 ++++++++------ src/SMAPI.Toolkit/SemanticVersion.cs | 61 ++++++++++++++-------- src/SMAPI.sln.DotSettings | 1 + src/SMAPI/SemanticVersion.cs | 31 ++++++----- 5 files changed, 91 insertions(+), 75 deletions(-) diff --git a/src/SMAPI.Tests/Utilities/SemanticVersionTests.cs b/src/SMAPI.Tests/Utilities/SemanticVersionTests.cs index 599ac839..fedadba6 100644 --- a/src/SMAPI.Tests/Utilities/SemanticVersionTests.cs +++ b/src/SMAPI.Tests/Utilities/SemanticVersionTests.cs @@ -1,5 +1,3 @@ -#nullable disable - using System; using System.Diagnostics.CodeAnalysis; using Newtonsoft.Json; @@ -63,10 +61,10 @@ namespace SMAPI.Tests.Utilities [TestCase("apple")] [TestCase("-apple")] [TestCase("-5")] - public void Constructor_FromString_WithInvalidValues(string input) + public void Constructor_FromString_WithInvalidValues(string? input) { if (input == null) - this.AssertAndLogException(() => new SemanticVersion(input)); + this.AssertAndLogException(() => new SemanticVersion(input!)); else this.AssertAndLogException(() => new SemanticVersion(input)); } @@ -93,7 +91,7 @@ namespace SMAPI.Tests.Utilities [TestCase("1.2.3.4-some-tag.4 ")] public void Constructor_FromString_Standard_DisallowsNonStandardVersion(string input) { - Assert.Throws(() => new SemanticVersion(input)); + Assert.Throws(() => _ = new SemanticVersion(input)); } /// Assert the parsed version when constructed from standard parts. @@ -112,7 +110,7 @@ namespace SMAPI.Tests.Utilities [TestCase(1, 2, 3, "some-tag.4 ", null, ExpectedResult = "1.2.3-some-tag.4")] [TestCase(1, 2, 3, "some-tag.4 ", "build.004", ExpectedResult = "1.2.3-some-tag.4+build.004")] [TestCase(1, 2, 0, null, "3.4.5-build.004", ExpectedResult = "1.2.0+3.4.5-build.004")] - public string Constructor_FromParts(int major, int minor, int patch, string prerelease, string build) + public string Constructor_FromParts(int major, int minor, int patch, string? prerelease, string? build) { // act ISemanticVersion version = new SemanticVersion(major, minor, patch, prerelease, build); @@ -222,11 +220,11 @@ namespace SMAPI.Tests.Utilities // null [TestCase("1.0.0", null, ExpectedResult = 1)] // null is always less than any value per CompareTo remarks - public int CompareTo(string versionStrA, string versionStrB) + public int CompareTo(string versionStrA, string? versionStrB) { // arrange ISemanticVersion versionA = new SemanticVersion(versionStrA); - ISemanticVersion versionB = versionStrB != null + ISemanticVersion? versionB = versionStrB != null ? new SemanticVersion(versionStrB) : null; @@ -270,11 +268,11 @@ namespace SMAPI.Tests.Utilities // null [TestCase("1.0.0", null, ExpectedResult = false)] // null is always less than any value per CompareTo remarks - public bool IsOlderThan(string versionStrA, string versionStrB) + public bool IsOlderThan(string versionStrA, string? versionStrB) { // arrange ISemanticVersion versionA = new SemanticVersion(versionStrA); - ISemanticVersion versionB = versionStrB != null + ISemanticVersion? versionB = versionStrB != null ? new SemanticVersion(versionStrB) : null; @@ -319,11 +317,11 @@ namespace SMAPI.Tests.Utilities // null [TestCase("1.0.0", null, ExpectedResult = true)] // null is always less than any value per CompareTo remarks - public bool IsNewerThan(string versionStrA, string versionStrB) + public bool IsNewerThan(string versionStrA, string? versionStrB) { // arrange ISemanticVersion versionA = new SemanticVersion(versionStrA); - ISemanticVersion versionB = versionStrB != null + ISemanticVersion? versionB = versionStrB != null ? new SemanticVersion(versionStrB) : null; @@ -356,13 +354,13 @@ namespace SMAPI.Tests.Utilities [TestCase("1.0-beta.2", "1.0-beta.10", "1.0-beta.3", ExpectedResult = false)] [TestCase("1.0-beta-2", "1.0-beta-10", "1.0-beta-3", ExpectedResult = false)] [TestCase("1.0.0", "1.0.0", null, ExpectedResult = false)] // null is always less than any value per CompareTo remarks - public bool IsBetween(string versionStr, string lowerStr, string upperStr) + public bool IsBetween(string versionStr, string? lowerStr, string? upperStr) { // arrange - ISemanticVersion lower = lowerStr != null + ISemanticVersion? lower = lowerStr != null ? new SemanticVersion(lowerStr) : null; - ISemanticVersion upper = upperStr != null + ISemanticVersion? upper = upperStr != null ? new SemanticVersion(upperStr) : null; ISemanticVersion version = new SemanticVersion(versionStr); @@ -436,7 +434,7 @@ namespace SMAPI.Tests.Utilities /// The prerelease tag. /// The build metadata. /// Whether the version should be marked as non-standard. - private void AssertParts(ISemanticVersion version, int major, int minor, int patch, string prerelease, string build, bool nonStandard) + private void AssertParts(ISemanticVersion version, int major, int minor, int patch, string? prerelease, string? build, bool nonStandard) { Assert.AreEqual(major, version.MajorVersion, "The major version doesn't match."); Assert.AreEqual(minor, version.MinorVersion, "The minor version doesn't match."); @@ -449,9 +447,8 @@ namespace SMAPI.Tests.Utilities /// Assert that the expected exception type is thrown, and log the action output and thrown exception. /// The expected exception type. /// The action which may throw the exception. - /// The message to log if the expected exception isn't thrown. [SuppressMessage("ReSharper", "UnusedParameter.Local", Justification = "The message argument is deliberately only used in precondition checks since this is an assertion method.")] - private void AssertAndLogException(Func action, string message = null) + private void AssertAndLogException(Func action) where T : Exception { this.AssertAndLogException(() => @@ -466,7 +463,7 @@ namespace SMAPI.Tests.Utilities /// The action which may throw the exception. /// The message to log if the expected exception isn't thrown. [SuppressMessage("ReSharper", "UnusedParameter.Local", Justification = "The message argument is deliberately only used in precondition checks since this is an assertion method.")] - private void AssertAndLogException(Action action, string message = null) + private void AssertAndLogException(Action action, string? message = null) where T : Exception { try diff --git a/src/SMAPI.Toolkit.CoreInterfaces/ISemanticVersion.cs b/src/SMAPI.Toolkit.CoreInterfaces/ISemanticVersion.cs index 52cec52e..7998272f 100644 --- a/src/SMAPI.Toolkit.CoreInterfaces/ISemanticVersion.cs +++ b/src/SMAPI.Toolkit.CoreInterfaces/ISemanticVersion.cs @@ -1,5 +1,3 @@ -#nullable disable - using System; namespace StardewModdingAPI @@ -20,10 +18,10 @@ namespace StardewModdingAPI int PatchVersion { get; } /// An optional prerelease tag. - string PrereleaseTag { get; } + string? PrereleaseTag { get; } /// Optional build metadata. This is ignored when determining version precedence. - string BuildMetadata { get; } + string? BuildMetadata { get; } /********* @@ -34,32 +32,38 @@ namespace StardewModdingAPI /// Get whether this version is older than the specified version. /// The version to compare with this instance. - bool IsOlderThan(ISemanticVersion other); + /// Although the parameter is nullable, it isn't optional. A null version is considered earlier than every possible valid version, so passing null to will always return false. + bool IsOlderThan(ISemanticVersion? other); /// Get whether this version is older than the specified version. - /// The version to compare with this instance. + /// The version to compare with this instance. A null value is never older. /// The specified version is not a valid semantic version. - bool IsOlderThan(string other); + /// Although the parameter is nullable, it isn't optional. A null version is considered earlier than every possible valid version, so passing null to will always return false. + bool IsOlderThan(string? other); /// Get whether this version is newer than the specified version. - /// The version to compare with this instance. - bool IsNewerThan(ISemanticVersion other); + /// The version to compare with this instance. A null value is always older. + /// Although the parameter is nullable, it isn't optional. A null version is considered earlier than every possible valid version, so passing null to will always return true. + bool IsNewerThan(ISemanticVersion? other); /// Get whether this version is newer than the specified version. - /// The version to compare with this instance. + /// The version to compare with this instance. A null value is always older. /// The specified version is not a valid semantic version. - bool IsNewerThan(string other); + /// Although the parameter is nullable, it isn't optional. A null version is considered earlier than every possible valid version, so passing null to will always return true. + bool IsNewerThan(string? other); /// Get whether this version is between two specified versions (inclusively). - /// The minimum version. - /// The maximum version. - bool IsBetween(ISemanticVersion min, ISemanticVersion max); + /// The minimum version. A null value is always older. + /// The maximum version. A null value is never newer. + /// Although the and parameters are nullable, they are not optional. A null version is considered earlier than every possible valid version. For example, passing null to will always return false, since no valid version can be earlier than null. + bool IsBetween(ISemanticVersion? min, ISemanticVersion? max); /// Get whether this version is between two specified versions (inclusively). - /// The minimum version. - /// The maximum version. + /// The minimum version. A null value is always older. + /// The maximum version. A null value is never newer. /// One of the specified versions is not a valid semantic version. - bool IsBetween(string min, string max); + /// Although the and parameters are nullable, they are not optional. A null version is considered earlier than every possible valid version. For example, passing null to will always return false, since no valid version can be earlier than null. + bool IsBetween(string? min, string? max); /// Get a string representation of the version. string ToString(); diff --git a/src/SMAPI.Toolkit/SemanticVersion.cs b/src/SMAPI.Toolkit/SemanticVersion.cs index 41ae12eb..cea8c447 100644 --- a/src/SMAPI.Toolkit/SemanticVersion.cs +++ b/src/SMAPI.Toolkit/SemanticVersion.cs @@ -1,6 +1,5 @@ -#nullable disable - using System; +using System.Diagnostics.CodeAnalysis; using System.Text.RegularExpressions; using StardewModdingAPI.Toolkit.Framework; @@ -40,10 +39,10 @@ namespace StardewModdingAPI.Toolkit public int PlatformRelease { get; } /// - public string PrereleaseTag { get; } + public string? PrereleaseTag { get; } /// - public string BuildMetadata { get; } + public string? BuildMetadata { get; } /********* @@ -56,7 +55,7 @@ namespace StardewModdingAPI.Toolkit /// The platform-specific version (if applicable). /// An optional prerelease tag. /// Optional build metadata. This is ignored when determining version precedence. - public SemanticVersion(int major, int minor, int patch, int platformRelease = 0, string prereleaseTag = null, string buildMetadata = null) + public SemanticVersion(int major, int minor, int patch, int platformRelease = 0, string? prereleaseTag = null, string? buildMetadata = null) { this.MajorVersion = major; this.MinorVersion = minor; @@ -106,7 +105,7 @@ namespace StardewModdingAPI.Toolkit } /// - public int CompareTo(ISemanticVersion other) + public int CompareTo(ISemanticVersion? other) { return other == null ? 1 @@ -114,7 +113,7 @@ namespace StardewModdingAPI.Toolkit } /// - public bool Equals(ISemanticVersion other) + public bool Equals(ISemanticVersion? other) { return other != null && this.CompareTo(other) == 0; } @@ -126,15 +125,15 @@ namespace StardewModdingAPI.Toolkit } /// - public bool IsOlderThan(ISemanticVersion other) + public bool IsOlderThan(ISemanticVersion? other) { return this.CompareTo(other) < 0; } /// - public bool IsOlderThan(string other) + public bool IsOlderThan(string? other) { - ISemanticVersion otherVersion = other != null + ISemanticVersion? otherVersion = other != null ? new SemanticVersion(other, allowNonStandard: true) : null; @@ -142,15 +141,15 @@ namespace StardewModdingAPI.Toolkit } /// - public bool IsNewerThan(ISemanticVersion other) + public bool IsNewerThan(ISemanticVersion? other) { return this.CompareTo(other) > 0; } /// - public bool IsNewerThan(string other) + public bool IsNewerThan(string? other) { - ISemanticVersion otherVersion = other != null + ISemanticVersion? otherVersion = other != null ? new SemanticVersion(other, allowNonStandard: true) : null; @@ -158,18 +157,18 @@ namespace StardewModdingAPI.Toolkit } /// - public bool IsBetween(ISemanticVersion min, ISemanticVersion max) + public bool IsBetween(ISemanticVersion? min, ISemanticVersion? max) { return this.CompareTo(min) >= 0 && this.CompareTo(max) <= 0; } /// - public bool IsBetween(string min, string max) + public bool IsBetween(string? min, string? max) { - ISemanticVersion minVersion = min != null + ISemanticVersion? minVersion = min != null ? new SemanticVersion(min, allowNonStandard: true) : null; - ISemanticVersion maxVersion = max != null + ISemanticVersion? maxVersion = max != null ? new SemanticVersion(max, allowNonStandard: true) : null; @@ -199,7 +198,12 @@ namespace StardewModdingAPI.Toolkit /// The version string. /// The parsed representation. /// Returns whether parsing the version succeeded. - public static bool TryParse(string version, out ISemanticVersion parsed) + public static bool TryParse(string? version, +#if NET5_0_OR_GREATER + [NotNullWhen(true)] +#endif + out ISemanticVersion? parsed + ) { return SemanticVersion.TryParse(version, allowNonStandard: false, out parsed); } @@ -209,8 +213,19 @@ namespace StardewModdingAPI.Toolkit /// Whether to allow non-standard extensions to semantic versioning. /// The parsed representation. /// Returns whether parsing the version succeeded. - public static bool TryParse(string version, bool allowNonStandard, out ISemanticVersion parsed) + public static bool TryParse(string? version, bool allowNonStandard, +#if NET5_0_OR_GREATER + [NotNullWhen(true)] +#endif + out ISemanticVersion? parsed + ) { + if (version == null) + { + parsed = null; + return false; + } + try { parsed = new SemanticVersion(version, allowNonStandard); @@ -229,7 +244,7 @@ namespace StardewModdingAPI.Toolkit *********/ /// Get a normalized prerelease or build tag. /// The tag to normalize. - private string GetNormalizedTag(string tag) + private string? GetNormalizedTag(string? tag) { tag = tag?.Trim(); return !string.IsNullOrWhiteSpace(tag) ? tag : null; @@ -241,7 +256,7 @@ namespace StardewModdingAPI.Toolkit /// The patch version to compare with this instance. /// The non-standard platform release to compare with this instance. /// The prerelease tag to compare with this instance. - private int CompareTo(int otherMajor, int otherMinor, int otherPatch, int otherPlatformRelease, string otherTag) + private int CompareTo(int otherMajor, int otherMinor, int otherPatch, int otherPlatformRelease, string? otherTag) { const int same = 0; const int curNewer = 1; @@ -270,8 +285,8 @@ namespace StardewModdingAPI.Toolkit return curOlder; // compare two prerelease tag values - string[] curParts = this.PrereleaseTag.Split('.', '-'); - string[] otherParts = otherTag.Split('.', '-'); + string[] curParts = this.PrereleaseTag?.Split('.', '-') ?? Array.Empty(); + string[] otherParts = otherTag?.Split('.', '-') ?? Array.Empty(); int length = Math.Max(curParts.Length, otherParts.Length); for (int i = 0; i < length; i++) { diff --git a/src/SMAPI.sln.DotSettings b/src/SMAPI.sln.DotSettings index b85185d5..5b35c615 100644 --- a/src/SMAPI.sln.DotSettings +++ b/src/SMAPI.sln.DotSettings @@ -73,5 +73,6 @@ True True True + True True \ No newline at end of file diff --git a/src/SMAPI/SemanticVersion.cs b/src/SMAPI/SemanticVersion.cs index 4e484633..7a6cdcdd 100644 --- a/src/SMAPI/SemanticVersion.cs +++ b/src/SMAPI/SemanticVersion.cs @@ -1,6 +1,5 @@ -#nullable disable - using System; +using System.Diagnostics.CodeAnalysis; using Newtonsoft.Json; namespace StardewModdingAPI @@ -28,10 +27,10 @@ namespace StardewModdingAPI public int PatchVersion => this.Version.PatchVersion; /// - public string PrereleaseTag => this.Version.PrereleaseTag; + public string? PrereleaseTag => this.Version.PrereleaseTag; /// - public string BuildMetadata => this.Version.BuildMetadata; + public string? BuildMetadata => this.Version.BuildMetadata; /********* @@ -43,7 +42,7 @@ namespace StardewModdingAPI /// The patch version for backwards-compatible bug fixes. /// An optional prerelease tag. /// Optional build metadata. This is ignored when determining version precedence. - public SemanticVersion(int majorVersion, int minorVersion, int patchVersion, string prereleaseTag = null, string buildMetadata = null) + public SemanticVersion(int majorVersion, int minorVersion, int patchVersion, string? prereleaseTag = null, string? buildMetadata = null) : this(majorVersion, minorVersion, patchVersion, 0, prereleaseTag, buildMetadata) { } /// Construct an instance. @@ -54,7 +53,7 @@ namespace StardewModdingAPI /// The platform-specific version (if applicable). /// Optional build metadata. This is ignored when determining version precedence. [JsonConstructor] - internal SemanticVersion(int majorVersion, int minorVersion, int patchVersion, int platformRelease, string prereleaseTag = null, string buildMetadata = null) + internal SemanticVersion(int majorVersion, int minorVersion, int patchVersion, int platformRelease, string? prereleaseTag = null, string? buildMetadata = null) : this(new Toolkit.SemanticVersion(majorVersion, minorVersion, patchVersion, platformRelease, prereleaseTag, buildMetadata)) { } /// Construct an instance. @@ -93,49 +92,49 @@ namespace StardewModdingAPI /// /// The implementation is defined by Semantic Version 2.0 (https://semver.org/). - public int CompareTo(ISemanticVersion other) + public int CompareTo(ISemanticVersion? other) { return this.Version.CompareTo(other); } /// - public bool IsOlderThan(ISemanticVersion other) + public bool IsOlderThan(ISemanticVersion? other) { return this.Version.IsOlderThan(other); } /// - public bool IsOlderThan(string other) + public bool IsOlderThan(string? other) { return this.Version.IsOlderThan(other); } /// - public bool IsNewerThan(ISemanticVersion other) + public bool IsNewerThan(ISemanticVersion? other) { return this.Version.IsNewerThan(other); } /// - public bool IsNewerThan(string other) + public bool IsNewerThan(string? other) { return this.Version.IsNewerThan(other); } /// - public bool IsBetween(ISemanticVersion min, ISemanticVersion max) + public bool IsBetween(ISemanticVersion? min, ISemanticVersion? max) { return this.Version.IsBetween(min, max); } /// - public bool IsBetween(string min, string max) + public bool IsBetween(string? min, string? max) { return this.Version.IsBetween(min, max); } /// - public bool Equals(ISemanticVersion other) + public bool Equals(ISemanticVersion? other) { return other != null && this.CompareTo(other) == 0; } @@ -156,9 +155,9 @@ namespace StardewModdingAPI /// The version string. /// The parsed representation. /// Returns whether parsing the version succeeded. - public static bool TryParse(string version, out ISemanticVersion parsed) + public static bool TryParse(string version, [NotNullWhen(true)] out ISemanticVersion? parsed) { - if (Toolkit.SemanticVersion.TryParse(version, out ISemanticVersion versionImpl)) + if (Toolkit.SemanticVersion.TryParse(version, out ISemanticVersion? versionImpl)) { parsed = new SemanticVersion(versionImpl); return true; -- cgit