Merge pull request #21 from natsnudasoft/common-abstractions

Provide abstractions of some common non-deterministic types
+semver: minor

src/NatsnudaLibrary/IDateTimeOffsetProvider.cs

@@ -0,0 +1,40 @@
+// <copyright file="IDateTimeOffsetProvider.cs" company="natsnudasoft">
+// Copyright (c) Adrian John Dunstan. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+namespace Natsnudasoft.NatsnudaLibrary
+{
+    using System;
+
+    /// <summary>
+    /// Provides abstractions of the non-deterministic members of <see cref="DateTimeOffset"/>.
+    /// </summary>
+    public interface IDateTimeOffsetProvider
+    {
+        /// <summary>
+        /// Gets a <see cref="DateTimeOffset"/> object that is set to the current date and time on
+        /// the current computer, with the offset set to the local time's offset from Coordinated
+        /// Universal Time (UTC).
+        /// </summary>
+        DateTimeOffset Now { get; }
+
+        /// <summary>
+        /// Gets a <see cref="DateTimeOffset"/> object whose date and time are set to the current
+        /// Coordinated Universal Time (UTC) date and time and whose offset is
+        /// <see cref="TimeSpan.Zero"/>.
+        /// </summary>
+        DateTimeOffset UtcNow { get; }
+    }
+}

src/NatsnudaLibrary/IDateTimeProvider.cs

@@ -0,0 +1,44 @@
+// <copyright file="IDateTimeProvider.cs" company="natsnudasoft">
+// Copyright (c) Adrian John Dunstan. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+namespace Natsnudasoft.NatsnudaLibrary
+{
+    using System;
+
+    /// <summary>
+    /// Provides abstractions of the non-deterministic members of <see cref="DateTime"/>.
+    /// </summary>
+    public interface IDateTimeProvider
+    {
+        /// <summary>
+        /// Gets a <see cref="DateTime"/> object that is set to the current date and time on this
+        /// computer, expressed as the local time.
+        /// </summary>
+        DateTime Now { get; }
+
+        /// <summary>
+        /// Gets a <see cref="DateTime"/> object that is set to the current date on this
+        /// computer, with the time component set to 00:00:00.
+        /// </summary>
+        DateTime Today { get; }
+
+        /// <summary>
+        /// Gets a <see cref="DateTime"/> object that is set to the current date and time on this
+        /// computer, expressed as the Coordinated Universal Time (UTC).
+        /// </summary>
+        DateTime UtcNow { get; }
+    }
+}

src/NatsnudaLibrary/IGuidProvider.cs

@@ -0,0 +1,32 @@
+// <copyright file="IGuidProvider.cs" company="natsnudasoft">
+// Copyright (c) Adrian John Dunstan. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+namespace Natsnudasoft.NatsnudaLibrary
+{
+    using System;
+
+    /// <summary>
+    /// Provides abstractions of the non-deterministic members of <see cref="Guid"/>.
+    /// </summary>
+    public interface IGuidProvider
+    {
+        /// <summary>
+        /// Create a new instance of <see cref="Guid"/>.
+        /// </summary>
+        /// <returns>A new <see cref="Guid"/> object.</returns>
+        Guid NewGuid();
+    }
+}

src/NatsnudaLibrary/IRandom.cs

@@ -0,0 +1,65 @@
+// <copyright file="IRandom.cs" company="natsnudasoft">
+// Copyright (c) Adrian John Dunstan. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+namespace Natsnudasoft.NatsnudaLibrary
+{
+    /// <summary>
+    /// Provides an interface describing the actions of a pseudo-random number generator.
+    /// </summary>
+    public interface IRandom
+    {
+        /// <summary>
+        /// Returns a non-negative random integer.
+        /// </summary>
+        /// <returns>A 32-bit signed integer that is greater than or equal to 0 and less than
+        /// <see cref="int.MaxValue"/>.</returns>
+        int Next();
+
+        /// <summary>
+        /// Returns a non-negative random integer that is less than the specified maximum.
+        /// </summary>
+        /// <param name="maxValue">The exclusive upper bound of the random number to be generated.
+        /// </param>
+        /// <returns>A 32-bit signed integer that is greater than or equal to 0, and less than
+        /// <paramref name="maxValue"/>.</returns>
+        int Next(int maxValue);
+
+        /// <summary>
+        /// Returns a random integer that is within a specified range.
+        /// </summary>
+        /// <param name="minValue">The inclusive lower bound of the random number to be generated.
+        /// </param>
+        /// <param name="maxValue">The exclusive upper bound of the random number to be generated.
+        /// </param>
+        /// <returns>A 32-bit signed integer that is greater than or equal to
+        /// <paramref name="minValue"/>, and less than <paramref name="maxValue"/>.</returns>
+        int Next(int minValue, int maxValue);
+
+        /// <summary>
+        /// Fills the elements of a specified array of bytes with random numbers.
+        /// </summary>
+        /// <param name="buffer">An array of bytes to fill with random numbers.</param>
+        void NextBytes(byte[] buffer);
+
+        /// <summary>
+        /// Returns a random floating-point number that is greater than or equal to 0.0, and less
+        /// than 1.0.
+        /// </summary>
+        /// <returns>A double-precision floating point number that is greater than or equal to 0.0,
+        /// and less than 1.0.</returns>
+        double NextDouble();
+    }
+}

src/NatsnudaLibrary/NatsnudaLibrary.csproj

@@ -60,8 +60,16 @@
     <Compile Include="..\..\CommonSuppressions.cs">
       <Link>CommonSuppressions.cs</Link>
     </Compile>
+    <Compile Include="IDateTimeOffsetProvider.cs" />
+    <Compile Include="IDateTimeProvider.cs" />
+    <Compile Include="IGuidProvider.cs" />
+    <Compile Include="IRandom.cs" />
     <Compile Include="ParameterValidation.cs" />
     <Compile Include="Properties\AssemblyInfo.cs" />
+    <Compile Include="SystemDateTimeOffsetProvider.cs" />
+    <Compile Include="SystemDateTimeProvider.cs" />
+    <Compile Include="SystemGuidProvider.cs" />
+    <Compile Include="SystemRandom.cs" />
     <Compile Include="ValidatedNotNullAttribute.cs" />
   </ItemGroup>
   <ItemGroup>

src/NatsnudaLibrary/SystemDateTimeOffsetProvider.cs

@@ -0,0 +1,35 @@
+// <copyright file="SystemDateTimeOffsetProvider.cs" company="natsnudasoft">
+// Copyright (c) Adrian John Dunstan. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+namespace Natsnudasoft.NatsnudaLibrary
+{
+    using System;
+
+    /// <summary>
+    /// Represents a class which is capable of providing values of <see cref="DateTimeOffset"/>
+    /// using the default <see cref="DateTimeOffset"/> members.
+    /// </summary>
+    /// <seealso cref="IDateTimeOffsetProvider" />
+    [System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage]
+    public class SystemDateTimeOffsetProvider : IDateTimeOffsetProvider
+    {
+        /// <inheritdoc/>
+        public DateTimeOffset Now => DateTimeOffset.Now;
+
+        /// <inheritdoc/>
+        public DateTimeOffset UtcNow => DateTimeOffset.UtcNow;
+    }
+}

src/NatsnudaLibrary/SystemDateTimeProvider.cs

@@ -0,0 +1,38 @@
+// <copyright file="SystemDateTimeProvider.cs" company="natsnudasoft">
+// Copyright (c) Adrian John Dunstan. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+namespace Natsnudasoft.NatsnudaLibrary
+{
+    using System;
+
+    /// <summary>
+    /// Represents a class which is capable of providing values of <see cref="DateTime"/> using the
+    /// default <see cref="DateTime"/> members.
+    /// </summary>
+    /// <seealso cref="IDateTimeProvider" />
+    [System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage]
+    public class SystemDateTimeProvider : IDateTimeProvider
+    {
+        /// <inheritdoc/>
+        public DateTime Now => DateTime.Now;
+
+        /// <inheritdoc/>
+        public DateTime Today => DateTime.Today;
+
+        /// <inheritdoc/>
+        public DateTime UtcNow => DateTime.UtcNow;
+    }
+}

src/NatsnudaLibrary/SystemGuidProvider.cs

@@ -0,0 +1,34 @@
+// <copyright file="SystemGuidProvider.cs" company="natsnudasoft">
+// Copyright (c) Adrian John Dunstan. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+namespace Natsnudasoft.NatsnudaLibrary
+{
+    using System;
+    using System.Security;
+
+    /// <summary>
+    /// Represents a class which is capable of providing values of <see cref="Guid"/> using the
+    /// default <see cref="Guid"/> members.
+    /// </summary>
+    /// <seealso cref="IGuidProvider" />
+    [System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage]
+    public class SystemGuidProvider : IGuidProvider
+    {
+        /// <inheritdoc/>
+        [SecuritySafeCritical]
+        public Guid NewGuid() => Guid.NewGuid();
+    }
+}

src/NatsnudaLibrary/SystemRandom.cs

@@ -0,0 +1,51 @@
+// <copyright file="SystemRandom.cs" company="natsnudasoft">
+// Copyright (c) Adrian John Dunstan. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+namespace Natsnudasoft.NatsnudaLibrary
+{
+    using System;
+
+    /// <summary>
+    /// A wrapper around the <see cref="Random"/> class, that implements the <see cref="IRandom"/>
+    /// interface.
+    /// </summary>
+    /// <seealso cref="Random" />
+    /// <seealso cref="IRandom" />
+    [System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage]
+    public class SystemRandom : Random, IRandom
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="SystemRandom"/> class, using a
+        /// time-dependent default seed value.
+        /// </summary>
+        public SystemRandom()
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="SystemRandom"/> class, using the specified
+        /// seed value.
+        /// </summary>
+        /// <param name="seed">A number used to calculate a starting value for the pseudo-random
+        /// number sequence. If a negative number is specified, the absolute value of the number is
+        /// used.
+        /// </param>
+        public SystemRandom(int seed)
+            : base(seed)
+        {
+        }
+    }
+}