Squid.cs

// // ***********************************************************************
// // Solution         : Inno.Api.v2
// // Assembly         : FCS.Lib.Utility
// // Filename         : Squid.cs
// // Created          : 2025-01-03 14:01
// // Last Modified By : dev
// // Last Modified On : 2025-01-04 12:01
// // ***********************************************************************
// // <copyright company="Frede Hundewadt">
// //     Copyright (C) 2010-2025 Frede Hundewadt
// //     This program is free software: you can redistribute it and/or modify
// //     it under the terms of the GNU Affero General Public License as
// //     published by the Free Software Foundation, either version 3 of the
// //     License, or (at your option) any later version.
// //
// //     This program is distributed in the hope that it will be useful,
// //     but WITHOUT ANY WARRANTY; without even the implied warranty of
// //     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// //     GNU Affero General Public License for more details.
// //
// //     You should have received a copy of the GNU Affero General Public License
// //     along with this program.  If not, see [https://www.gnu.org/licenses]
// // </copyright>
// // <summary></summary>
// // ***********************************************************************

using System;
using System.Diagnostics;

namespace FCS.Lib.Utility;

/// <summary>
///     Represents a globally unique identifier (GUID) encoded in a custom format.
/// </summary>
/// <remarks>
///     The <see cref="FCS.Lib.Utility.Squid" /> struct provides functionality for encoding and decoding GUIDs
///     into a custom string format, as well as creating new GUIDs and performing various operations
///     such as equality checks and conversions.
/// </remarks>
[DebuggerDisplay("{" + nameof(Value) + "}")]
public readonly struct Squid : IEquatable<Squid>
{
    /// <summary>
    ///     A read-only object of the Squid struct.
    ///     Value is guaranteed to be all zeroes.
    /// </summary>
    public static readonly Squid Empty = new(Guid.Empty);


    /// <summary>
    ///     Creates a new Squid from a Squid encoded string.
    /// </summary>
    /// <param name="value">A valid Squid encoded string.</param>
    public Squid(string value)
    {
        Value = value;
        Guid = DecodeSquid(value);
    }


    /// <summary>
    ///     Creates a new Squid with the given <see cref="System.Guid" />.
    /// </summary>
    /// <param name="obj">A valid System.Guid object.</param>
    public Squid(Guid obj)
    {
        Value = EncodeGuid(obj);
        Guid = obj;
    }


    /// <summary>
    ///     Gets the underlying <see cref="System.Guid" /> for the encoded Squid.
    /// </summary>
    /// <value>The unique identifier.</value>
    public Guid Guid { get; }

    /// <summary>
    ///     The encoded string value of the <see cref="Guid" />
    ///     as an URL-safe Base64 string.
    /// </summary>
    /// <value>The value.</value>
    public string Value { get; }


    /// <summary>
    ///     Returns the encoded URL-safe Base64 string.
    /// </summary>
    /// <returns>A <see cref="string" /> that represents this instance.</returns>
    public override string ToString()
    {
        return Value;
    }


    /// <summary>
    ///     Returns a value indicating whether this object and a specified object represent the same type and value.
    ///     Compares for equality against other string, Guid and Squid types.
    /// </summary>
    /// <param name="obj">A System.String, System.Guid or Squid object</param>
    /// <returns><c>true</c> if the specified <see cref="object" /> is equal to this instance; otherwise, <c>false</c>.</returns>
    public override bool Equals(object obj)
    {
        return obj is Squid other && Equals(other);
    }


    /// <summary>
    ///     Equality comparison
    /// </summary>
    /// <param name="obj">A valid Squid object</param>
    /// <returns>A boolean indicating equality.</returns>
    public bool Equals(Squid obj)
    {
        return Guid.Equals(obj.Guid) && Value == obj.Value;
    }


    /// <summary>
    ///     Returns the hash code for the underlying <see cref="System.Guid" />.
    /// </summary>
    /// <returns>A hash code for this instance, suitable for use in hashing algorithms and data structures like a hash table.</returns>
    public override int GetHashCode()
    {
        unchecked
        {
            return (Guid.GetHashCode() * 397) ^ (Value != null ? Value.GetHashCode() : 0);
        }
    }


    /// <summary>
    ///     Initialises a new object of the Squid using <see cref="Guid.NewGuid()" />.
    /// </summary>
    /// <returns>New Squid object</returns>
    public static Squid NewGuid()
    {
        return new Squid(Guid.NewGuid());
    }


    /// <summary>
    ///     Encode string as a new Squid encoded string.
    ///     The encoding is similar to Base64 with
    ///     non-URL safe characters replaced, and padding removed.
    /// </summary>
    /// <param name="value">A valid <see cref="System.Guid" />.Tostring().</param>
    /// <returns>A 22 character URL-safe Base64 string.</returns>
    public static string EncodeString(string value)
    {
        var guid = new Guid(value);
        return EncodeGuid(guid);
    }


    /// <summary>
    ///     Encode a <see cref="System.Guid" /> object to Squid.
    ///     The encoding is similar to Base64 with
    ///     non-URL safe characters replaced, and padding removed.
    /// </summary>
    /// <param name="obj">A valid <see cref="System.Guid" /> object.</param>
    /// <returns>A 22 character URL-safe Base64 string.</returns>
    public static string EncodeGuid(Guid obj)
    {
        var encoded = Convert.ToBase64String(obj.ToByteArray());
        encoded = encoded
            .Replace("/", "_")
            .Replace("+", "-");
        return encoded.Substring(0, 22);
    }


    /// <summary>
    ///     Decode Squid string to a <see cref="System.Guid" />.
    ///     See also <seealso cref="TryDecode(string, out System.Guid)" /> or
    ///     <seealso cref="TryParse(string, out System.Guid)" />.
    /// </summary>
    /// <param name="value">A valid Squid encoded string.</param>
    /// <returns>A new <see cref="System.Guid" /> object from the parsed string.</returns>
    public static Guid DecodeSquid(string value)
    {
        if (value == null) return Empty;
        value = value
            .Replace("_", "/")
            .Replace("-", "+");

        var blob = Convert.FromBase64String(value + "==");
        return new Guid(blob);
    }


    /// <summary>
    ///     Squid to Guid.
    /// </summary>
    /// <param name="obj">A valid Squid object.</param>
    /// <returns>System.Guid object.</returns>
    public static Guid FromSquid(Squid obj)
    {
        return obj.Guid;
    }


    /// <summary>
    ///     String to Squid.
    /// </summary>
    /// <param name="value">String value to convert</param>
    /// <returns>A Squid object.</returns>
    public static Squid FromString(string value)
    {
        if (string.IsNullOrEmpty(value))
            return Empty;
        return TryParse(value, out Squid obj) ? obj : Empty;
    }


    /// <summary>
    ///     Decodes the given value to a <see cref="System.Guid" />.
    /// </summary>
    /// <param name="value">The Squid encoded string to decode.</param>
    /// <param name="obj">A new <see cref="System.Guid" /> object from the parsed string.</param>
    /// <returns>A boolean indicating if the decode was successful.</returns>
    public static bool TryDecode(string value, out Guid obj)
    {
        try
        {
            // Decode as Squid
            obj = DecodeSquid(value);
            return true;
        }
        catch (Exception)
        {
            // Return empty Guid
            obj = Guid.Empty;
            return false;
        }
    }


    /// <summary>
    ///     Tries to parse the given string value and
    ///     outputs the <see cref="Squid" /> object.
    /// </summary>
    /// <param name="value">The Squid encoded string or string representation of a Guid.</param>
    /// <param name="obj">A new <see cref="Squid" /> object from the parsed string.</param>
    /// <returns>A boolean indicating if the parse was successful.</returns>
    public static bool TryParse(string value, out Squid obj)
    {
        // Parse as Squid string.
        if (TryDecode(value, out var oGuid))
        {
            obj = oGuid;
            return true;
        }

        // Parse as Guid string.
        if (Guid.TryParse(value, out oGuid))
        {
            obj = oGuid;
            return true;
        }

        obj = Empty;
        return false;
    }


    /// <summary>
    ///     Tries to parse the string value and
    ///     outputs the underlying <see cref="System.Guid" /> object.
    /// </summary>
    /// <param name="value">The Squid encoded string or string representation of a Guid.</param>
    /// <param name="obj">A new <see cref="System.Guid" /> object from the parsed string.</param>
    /// <returns>A boolean indicating if the parse was successful.</returns>
    public static bool TryParse(string value, out Guid obj)
    {
        // Try a Squid string.
        if (TryDecode(value, out obj))
            return true;

        // Try a Guid string.
        if (Guid.TryParse(value, out obj))
            return true;

        obj = Guid.Empty;
        return false;
    }


    #region Operators

    /// <summary>
    ///     Determines if both Squid objects have the same
    ///     underlying <see cref="System.Guid" /> value.
    /// </summary>
    /// <param name="x">The x.</param>
    /// <param name="y">The y.</param>
    /// <returns>The result of the operator.</returns>
    public static bool operator ==(Squid x, Squid y)
    {
        return x.Guid == y.Guid;
    }


    /// <summary>
    ///     Determines if both objects have the same
    ///     underlying <see cref="System.Guid" /> value.
    /// </summary>
    /// <param name="x">The x.</param>
    /// <param name="y">The y.</param>
    /// <returns>The result of the operator.</returns>
    public static bool operator ==(Squid x, Guid y)
    {
        return x.Guid == y;
    }


    /// <summary>
    ///     Determines if both objects have the same
    ///     underlying <see cref="System.Guid" /> value.
    /// </summary>
    /// <param name="x">The x.</param>
    /// <param name="y">The y.</param>
    /// <returns>The result of the operator.</returns>
    public static bool operator ==(Guid x, Squid y)
    {
        return y == x; // NB: order of arguments
    }


    /// <summary>
    ///     Determines if both Squid objects do not have the same
    ///     underlying <see cref="System.Guid" /> value.
    /// </summary>
    /// <param name="x">The x.</param>
    /// <param name="y">The y.</param>
    /// <returns>The result of the operator.</returns>
    public static bool operator !=(Squid x, Squid y)
    {
        return !(x == y);
    }


    /// <summary>
    ///     Determines if both objects do not have the same
    ///     underlying <see cref="System.Guid" /> value.
    /// </summary>
    /// <param name="x">The x.</param>
    /// <param name="y">The y.</param>
    /// <returns>The result of the operator.</returns>
    public static bool operator !=(Squid x, Guid y)
    {
        return !(x == y);
    }


    /// <summary>
    ///     Determines if both objects do not have the same
    ///     underlying <see cref="System.Guid" /> value.
    /// </summary>
    /// <param name="x">The x.</param>
    /// <param name="y">The y.</param>
    /// <returns>The result of the operator.</returns>
    public static bool operator !=(Guid x, Squid y)
    {
        return !(x == y);
    }


    /// <summary>
    ///     Implicitly converts the Squid to
    ///     its string equivalent.
    /// </summary>
    /// <param name="oSquid">The o squid.</param>
    /// <returns>The result of the conversion.</returns>
    public static implicit operator string(Squid oSquid)
    {
        return oSquid.Value;
    }


    /// <summary>
    ///     Implicitly converts the Squid to
    ///     its <see cref="System.Guid" /> equivalent.
    /// </summary>
    /// <param name="oSquid">The o squid.</param>
    /// <returns>The result of the conversion.</returns>
    public static implicit operator Guid(Squid oSquid)
    {
        return oSquid.Guid;
    }


    /// <summary>
    ///     Implicitly converts the string to a Squid.
    /// </summary>
    /// <param name="value">The value.</param>
    /// <returns>The result of the conversion.</returns>
    public static implicit operator Squid(string value)
    {
        if (string.IsNullOrEmpty(value))
            return Empty;

        return TryParse(value, out Squid oSquid) ? oSquid : Empty;
    }


    /// <summary>
    ///     Implicitly converts the <see cref="System.Guid" /> to a Squid.
    /// </summary>
    /// <param name="oGuid">The o unique identifier.</param>
    /// <returns>The result of the conversion.</returns>
    public static implicit operator Squid(Guid oGuid)
    {
        return oGuid == Guid.Empty ? Empty : new Squid(oGuid);
    }

    #endregion
}