Skip to content

Commit

Permalink
Documentation improvements, version bump
Browse files Browse the repository at this point in the history
  • Loading branch information
@davetransom
davetransom committed May 8, 2020
1 parent fe93a55 commit 4124b7c
Show file tree
Hide file tree
Showing 2 changed files with 26 additions and 21 deletions.
7 changes: 4 additions & 3 deletions CSharpVitamins.ShortGuid/CSharpVitamins.ShortGuid.csproj
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,17 @@
<RootNamespace>CSharpVitamins</RootNamespace>
<Authors>Dave Transom</Authors>
<Company>CSharpVitamins</Company>
<Description>A convenience wrapper struct for dealing with URL-safe base64 encoded globally unique identifier (GUID), making a shorter string value (22 vs 36 characters long).</Description>
<Description>A convenience wrapper struct for dealing with URL-safe Base64 encoded globally unique identifiers (GUID), making a shorter string value (22 vs 36 characters long).</Description>
<PackageLicenseFile>LICENSE.md</PackageLicenseFile>
<PackageProjectUrl>https://github.com/csharpvitamins/csharpvitamins.shortguid/</PackageProjectUrl>
<PackageLicenseExpression></PackageLicenseExpression>
<RepositoryUrl>https://github.com/csharpvitamins/csharpvitamins.shortguid/</RepositoryUrl>
<PackageTags>Guid ShortGuid Identifiers Base64</PackageTags>
<PackageReleaseNotes>- 1.0.1 Target netstandard2.0 and net40
<PackageReleaseNotes>- 1.0.2 Fix: Ambiguous use of `==` operator when comparing Guid and ShortGuid instances
- 1.0.1 Target netstandard2.0 and net40
- 1.0.0 Initial release</PackageReleaseNotes>
<Copyright>Copyright 2007</Copyright>
<Version>1.0.1</Version>
<Version>1.0.2</Version>
</PropertyGroup>

<ItemGroup>
Expand Down
40 changes: 22 additions & 18 deletions CSharpVitamins.ShortGuid/ShortGuid.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,36 +4,39 @@
namespace CSharpVitamins
{
/// <summary>
/// A convenience wrapper struct for dealing with URL-safe Base64 encoded globally unique identifier (GUID),
/// A convenience wrapper struct for dealing with URL-safe Base64 encoded globally unique identifiers (GUID),
/// making a shorter string value (22 vs 36 characters long).
/// </summary>
/// <remarks>
/// URL-safe Base64? That's just a Base64 string with well known special characters replaced (/, +) or removed (==).
/// What is URL-safe Base64? That's just a Base64 string with well known special characters replaced (/, +)
/// or removed (==).
/// </remarks>
[DebuggerDisplay("{Value}")]
public struct ShortGuid
{
/// <summary>
/// A read-only instance of the ShortGuid struct whose value is guaranteed to be all zeroes.
/// A read-only instance of the ShortGuid struct whose value is guaranteed to be all zeroes i.e. equivilent
/// to <see cref="Guid.Empty"/>.
/// </summary>
public static readonly ShortGuid Empty = new ShortGuid(Guid.Empty);

Guid underlyingGuid;
string encodedString;

/// <summary>
/// Creates a new instance with the given Base64 encoded string.
/// (See also <seealso cref="ShortGuid.TryParse(string, out ShortGuid)"/>)
/// Creates a new instance with the given URL-safe Base64 encoded string.
/// See also <seealso cref="ShortGuid.TryParse(string, out ShortGuid)"/> which will try to coerce the
/// the value from URL-safe Base64 or normal Guid string
/// </summary>
/// <param name="value">A ShortGuid encoded string.</param>
/// <param name="value">A ShortGuid encoded string e.g. URL-safe Base64.</param>
public ShortGuid(string value)
{
encodedString = value;
underlyingGuid = Decode(value);
}

/// <summary>
/// Creates a new instance with the given Guid.
/// Creates a new instance with the given <see cref="Guid"/>.
/// </summary>
/// <param name="guid">The Guid to encode.</param>
public ShortGuid(Guid guid)
Expand All @@ -43,17 +46,17 @@ public ShortGuid(Guid guid)
}

/// <summary>
/// Gets the underlying Guid for the encoded ShortGuid.
/// Gets the underlying <see cref="Guid"/> for the encoded ShortGuid.
/// </summary>
public Guid Guid => underlyingGuid;

/// <summary>
/// Gets the encoded string value of the Guid.
/// Gets the encoded string value of the <see cref="Guid"/> i.e. a URL-safe Base64 string.
/// </summary>
public string Value => encodedString;

/// <summary>
/// Returns the encoded string value.
/// Returns the encoded URL-safe Base64 string.
/// </summary>
/// <returns></returns>
public override string ToString() => encodedString;
Expand Down Expand Up @@ -91,7 +94,7 @@ public override bool Equals(object obj)
}

/// <summary>
/// Returns the HashCode for the underlying Guid.
/// Returns the hash code for the underlying <see cref="Guid"/>.
/// </summary>
/// <returns></returns>
public override int GetHashCode() => underlyingGuid.GetHashCode();
Expand All @@ -107,7 +110,7 @@ public override bool Equals(object obj)
/// Base64, with some non-URL safe characters replaced, and padding removed.
/// </summary>
/// <param name="value">Any valid <see cref="Guid"/> string.</param>
/// <returns>A 22 character ShortGuid string.</returns>
/// <returns>A 22 character ShortGuid URL-safe Base64 string.</returns>
public static string Encode(string value)
{
var guid = new Guid(value);
Expand All @@ -119,7 +122,7 @@ public static string Encode(string value)
/// Base64, with some non-URL safe characters replaced, and padding removed.
/// </summary>
/// <param name="guid">The <see cref="Guid"/> to encode.</param>
/// <returns>A 22 character ShortGuid string.</returns>
/// <returns>A 22 character ShortGuid URL-safe Base64 string.</returns>
public static string Encode(Guid guid)
{
string encoded = Convert.ToBase64String(guid.ToByteArray());
Expand Down Expand Up @@ -218,7 +221,7 @@ public static bool TryDecode(string value, out Guid guid)
public static implicit operator string(ShortGuid shortGuid) => shortGuid.encodedString;

/// <summary>
/// Implicitly converts the ShortGuid to its Guid equivalent.
/// Implicitly converts the ShortGuid to its <see cref="Guid"/> equivalent.
/// </summary>
public static implicit operator Guid(ShortGuid shortGuid) => shortGuid.underlyingGuid;

Expand All @@ -233,11 +236,12 @@ public static implicit operator ShortGuid(string value)
if (TryParse(value, out ShortGuid shortGuid))
return shortGuid;

throw new FormatException("ShortGuid should contain 22 Base64 characters or Guid should contain 32 digits with 4 dashes (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).");
throw new FormatException("ShortGuid should contain 22 Base64 characters or "
+ "Guid should contain 32 digits with 4 dashes (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).");
}

/// <summary>
/// Implicitly converts the Guid to a ShortGuid.
/// Implicitly converts the <see cref="Guid"/> to a ShortGuid.
/// </summary>
public static implicit operator ShortGuid(Guid guid)
{
Expand All @@ -250,7 +254,7 @@ public static implicit operator ShortGuid(Guid guid)
#endregion

/// <summary>
/// Tries to parse the value as a ShortGuid or Guid string.
/// Tries to parse the value as a ShortGuid or <see cref="Guid"/> string.
/// </summary>
/// <param name="value">The ShortGuid encoded string or string representation of a Guid.</param>
/// <param name="shortGuid">A new <see cref="ShortGuid"/> instance from the parsed string.</param>
Expand All @@ -276,7 +280,7 @@ public static bool TryParse(string value, out ShortGuid shortGuid)
}

/// <summary>
/// Tries to parse the value as a ShortGuid or Guid string, and outputs the underlying Guid value.
/// Tries to parse the value as a ShortGuid or <see cref="Guid"/> string, and outputs the underlying <see cref="Guid"/> value.
/// </summary>
/// <param name="value">The ShortGuid encoded string or string representation of a Guid.</param>
/// <param name="guid">A new <see cref="Guid"/> instance from the parsed string.</param>
Expand Down

0 comments on commit 4124b7c

Please sign in to comment.