''' ----------------------------------------------------------------------------------------------------
''' <summary>
''' Returns the MSIL for the method body of the source <see cref="DynamicMethod"/>, as an array of bytes.
''' <para></para>
''' This is the necessary equivalent for <see cref="MethodBody.GetILCodeAsByteArray()"/> function, 
''' because <see cref="MethodBody.GetILCodeAsByteArray()"/> will not work with the method body returned by
''' an <see cref="DynamicMethod.GetMethodBody()"/> function since the IL code is stored in 
''' the MethodBuilder's ILGenerator.
''' </summary>
''' ----------------------------------------------------------------------------------------------------
''' <example> This is a code example #1.
''' <code language="VB.NET">
''' Dim dynMethod As New DynamicMethod("my_dynamic_method_name", Nothing, Type.EmptyTypes, restrictedSkipVisibility:=True)
''' Dim ilGen As ILGenerator = dynMethod.GetILGenerator(streamSize:=64)
''' ilGen.Emit(OpCodes.Nop)
''' 
''' Dim ilCode As Byte() = GetILCodeAsByteArray(dynMethod)
''' </code>
''' </example>
''' ----------------------------------------------------------------------------------------------------
''' <example> This is a code example #2.
''' <code language="VB.NET">
''' ' Create a simple dynamic method that has no parameters and does not return a value.
''' Dim dynMethod As New DynamicMethod("my_dynamic_method_name", Nothing, Type.EmptyTypes, restrictedSkipVisibility:=True)
''' 
''' ' Get an ILGenerator and emit a body for the dynamic method.
''' Dim il As ILGenerator = dynMethod.GetILGenerator(streamSize:=64)
''' il.Emit(OpCodes.Nop)
''' il.Emit(OpCodes.Ret)
''' 
''' ' Completes the dynamic method and creates a delegate that can be used to execute it.
''' ' Any further attempts to change the IL code will cause an exception.
''' Dim dynMethodInvoker As Action = CType(dynMethod.CreateDelegate(GetType(Action)), Action)
''' 
''' ' Get the IL code.
''' Dim ilCode As Byte() = GetILCodeAsByteArray(dynMethod)
''' 
''' Console.WriteLine($"Method body's IL bytes: {String.Join(", ", ilCode)}")
''' </code>
''' </example>
''' ----------------------------------------------------------------------------------------------------
''' <param name="dynMethod">
''' The source <see cref="DynamicMethod"/>.
''' </param>
''' ----------------------------------------------------------------------------------------------------
''' <returns>
''' The MSIL for the method body of the source <see cref="DynamicMethod"/>, as an array of bytes.
''' </returns>
''' ----------------------------------------------------------------------------------------------------
<DebuggerStepThrough>
<Extension>
<EditorBrowsable(EditorBrowsableState.Always)>
Public Function GetILCodeAsByteArray(dynMethod As DynamicMethod) As Byte()
 
    Dim bindingFlags As BindingFlags = BindingFlags.Instance Or BindingFlags.NonPublic
 
    ' First we try to retrieve the value of "m_resolver" field,
    ' which will always be null unless the dynamic method is completed
    ' by either calling 'dynMethod.CreateDelegate()' or 'dynMethod.Invoke()' function.
    ' Source: https://learn.microsoft.com/en-us/dotnet/api/system.reflection.emit.dynamicmethod.getilgenerator
    ' (in remarks section)
 
    ' Note that the dynamic method object does not know when it is ready for use
    ' since there is not API which indicates that IL generation has completed.
    ' Source: https://referencesource.microsoft.com/#mscorlib/system/reflection/emit/dynamicmethod.cs,7fc135a2ceea0854,references
    ' (in commentary lines)
 
    Dim resolver As Object = GetType(DynamicMethod).GetField("m_resolver", bindingFlags).GetValue(dynMethod)
    If resolver IsNot Nothing Then
        Return DirectCast(resolver.GetType().GetField("m_code", bindingFlags).GetValue(resolver), Byte())
 
    Else
        ' So, if the dynamic method is not completed, we will retrieve the "m_ILStream" field instead.
        ' The only difference I notice between "m_resolver" and "m_ILStream" fields is that the IL bytes in "m_ILStream"
        ' will have trailing zeros / null bytes depending on the amount of unused bytes in this stream.
        ' ( The buffer size for "m_ILStream" is allocated by a call to 'dynMethod.GetILGenerator(streamSize)' function. )
 
        Dim ilGen As ILGenerator = dynMethod.GetILGenerator()
 
        ' Conditional for .NET 4.x because DynamicILGenerator class derived from ILGenerator.
        ' Source: https://stackoverflow.com/a/4147132/1248295
        Dim ilStream As FieldInfo = If(Environment.Version.Major >= 4,
            ilGen.GetType().BaseType.GetField("m_ILStream", bindingFlags),
            ilGen.GetType().GetField("m_ILStream", bindingFlags))
 
        Return TryCast(ilStream.GetValue(ilGen), Byte())
    End If
 
End Function

Dim dynMethod As New DynamicMethod("my_dynamic_method_name", Nothing, Type.EmptyTypes, restrictedSkipVisibility:=True)
Dim ilGen As ILGenerator = dynMethod.GetILGenerator(streamSize:=64)
ilGen.Emit(OpCodes.Nop)
 
Dim ilCode As Byte() = GetILCodeAsByteArray(dynMethod)

Dim options As New MemorablePasswordOptions With {
    .NumberOfWords = 3,
    .MinimumWordLength = 4,
    .MaximumWordLength = 8,
    .SeparatorCharacters = "._-+".ToCharArray(),
    .StringCase = MemorablePasswordStringCase.TitleCase,
    .FixedPrefix = Nothing,
    .FixedSuffix = "!",
    .NumberOfDigitsPrefix = 0,
    .NumberOfDigitsSuffix = 3
}
 
Dim wordList As String() = System.IO.File.ReadAllLines(".\words.txt", Encoding.Default)
 
For i As Integer = 0 To 10
    Dim password As String = UtilPasswords.GenerateMemorablePassword(options, wordList)
    Console.WriteLine(password)
Next

Actor+Teaching_Spring-174!
Example_Hotel_Slavery_861!
Maximum-Accuse_Offense.016!
Banana.China.Baseball-154!
Attach+Wash-Wagon+647!
Consumer+Allow.Boom-946!
Employ+Lose+Opinion_106!
Feel.Carbon.Focus+176!
Candy-Remove+Kick+581!
Internal-Buddy_Wide-280!
Serious-Everyone+Approve-522!

Imports DevCase.Core.DataProcessing.Common
Imports DevCase.Core.Security.Passwords
Imports DevCase.Extensions
Imports DevCase.Runtime.Numerics
 
Imports System.Text
 
Public Class UtilPasswords
 
    ''' ----------------------------------------------------------------------------------------------------
    ''' <summary>
    ''' Generates a memorable password based on the provided options and word list.
    ''' <para></para>
    ''' A memorable password is a type of password that is designed to be easy to remember, 
    ''' while still providing a reasonable level of security. 
    ''' <para></para>
    ''' It is a password generation methodology that aims to be recalled by the user 
    ''' without the need for written notes or  relying solely on password managers.
    ''' <para></para>
    ''' The concept behind a memorable password is to create a combination of words, phrases, 
    ''' or memorable patterns that are personally meaningful to the user. 
    ''' This can include using familiar words, personal information, 
    ''' or unique combinations that have personal significance. 
    ''' <para></para>
    ''' The goal is to create a password that is both secure and memorable, 
    ''' striking a balance between convenience and protection.
    ''' </summary>
    ''' ----------------------------------------------------------------------------------------------------
    ''' <remarks>
    ''' The generated password by this function follows the following format:
    ''' (FixedPrefix)(DigitsPrefix+Separator)(Words+Separators)(Separator+DigitsSuffix)(FixedSuffix)
    ''' </remarks>
    ''' ----------------------------------------------------------------------------------------------------
    ''' <example> This is a code example.
    ''' <code language="VB.NET">
    ''' Dim options As New MemorablePasswordOptions With {
    '''     .NumberOfWords = 3,
    '''     .MinimumWordLength = 4,
    '''     .MaximumWordLength = 8,
    '''     .SeparatorCharacters = "._-+".ToCharArray(),
    '''     .StringCase = MemorablePasswordStringCase.TitleCase,
    '''     .FixedPrefix = Nothing,
    '''     .FixedSuffix = "!",
    '''     .NumberOfDigitsPrefix = 0,
    '''     .NumberOfDigitsSuffix = 3
    ''' }
    '''
    ''' Dim wordList As String() = System.IO.File.ReadAllLines(".\words.txt", Encoding.Default)
    '''
    ''' For i As Integer = 0 To 10
    '''     Dim password As String = GenerateMemorablePassword(options, wordList)
    '''     Console.WriteLine(password)
    ''' Next
    ''' </code>
    ''' </example>
    ''' ----------------------------------------------------------------------------------------------------
    ''' <param name="options">
    ''' The options for generating the memorable password.
    ''' </param>
    ''' 
    ''' <param name="wordList">
    ''' The list of words to choose from.
    ''' </param>
    ''' ----------------------------------------------------------------------------------------------------
    ''' <returns>
    ''' The resulting memorable password.
    ''' </returns>
    ''' ----------------------------------------------------------------------------------------------------
    <DebuggerStepThrough>
    Public Shared Function GenerateMemorablePassword(options As MemorablePasswordOptions, wordList As IEnumerable(Of String)) As String
 
        If options.NumberOfDigitsPrefix < 0 Then
            Throw New InvalidOperationException(
                $"Value of property: '{NameOf(options)}.{options.NumberOfDigitsPrefix}' must be zero or greather.")
        End If
 
        If options.NumberOfDigitsSuffix < 0 Then
            Throw New InvalidOperationException(
                $"Value of property: '{NameOf(options)}.{options.NumberOfDigitsSuffix}' must be zero or greather.")
        End If
 
        Dim filteredWords As IEnumerable(Of String) =
            wordList.Where(Function(word As String)
                               Return word.Length >= options.MinimumWordLength AndAlso
                                      word.Length <= options.MaximumWordLength
                           End Function)
 
        Dim filteredWordsCount As Integer = filteredWords.Count
        If filteredWordsCount = 0 Then
            Throw New InvalidOperationException(
                "The provided word list does not contain any word between the " &
                "minimum and maximum word length specified in properties: " &
                $"'{options}.{options.MinimumWordLength}' and '{options}.{options.MaximumWordLength}'.")
        End If
        If filteredWordsCount < options.NumberOfWords Then
            Throw New InvalidOperationException(
                "The provided word list does not contain the" &
                $"enough number of words specified in property: '{options}.{options.NumberOfWords}'.")
        End If
 
        Dim selectedWords As New HashSet(Of String)
        Do Until selectedWords.Count = options.NumberOfWords
            selectedWords.Add(filteredWords(RandomNumberGenerator.Instance.Next(0, filteredWordsCount)))
        Loop
 
        Dim separatorsCount As Integer
        If options.SeparatorCharacters IsNot Nothing Then
            separatorsCount = options.SeparatorCharacters.Length
        End If
 
        Const digits As String = "1234567890"
 
        Dim sb As New StringBuilder()
 
        ' 1. Append the fixed prefix if provided.
        sb.Append(options.FixedPrefix)
 
        ' 2. Append a prefix of digits if provided, and a separator if provided.
        If options.NumberOfDigitsPrefix <> 0 Then
            For i As Integer = 0 To options.NumberOfDigitsPrefix - 1
                sb.Append(digits(RandomNumberGenerator.Instance.Next(0, digits.Length)))
            Next
            If options.SeparatorCharacters IsNot Nothing AndAlso separatorsCount <> 0 Then
                sb.Append(options.SeparatorCharacters(RandomNumberGenerator.Instance.Next(0, separatorsCount)))
            End If
        End If
 
        ' 3. Append the selected words, together with the word separators if provided.
        Dim selectedWordsCount As Integer = selectedWords.Count
        For i As Integer = 0 To selectedWordsCount - 1
            sb.Append(StringExtensions.Rename(selectedWords(i), CType(options.StringCase, StringCase)))
            If i <> (selectedWordsCount - 1) Then
                If options.SeparatorCharacters IsNot Nothing AndAlso separatorsCount <> 0 Then
                    sb.Append(options.SeparatorCharacters(RandomNumberGenerator.Instance.Next(0, separatorsCount)))
                End If
            End If
        Next
 
        ' 4. Append a separator if provided, and a suffix of digits if provided.
        If options.NumberOfDigitsSuffix <> 0 Then
            If options.SeparatorCharacters IsNot Nothing AndAlso separatorsCount <> 0 Then
                sb.Append(options.SeparatorCharacters(RandomNumberGenerator.Instance.Next(0, separatorsCount)))
            End If
            For i As Integer = 0 To options.NumberOfDigitsSuffix - 1
                sb.Append(digits(RandomNumberGenerator.Instance.Next(0, digits.Length)))
            Next
        End If
 
        ' 5. Append the fixed suffix if provided.
        sb.Append(options.FixedSuffix)
 
        ' (FixedPrefix)(DigitsPrefix+Separator)(Words+Separators)(Separator+DigitsSuffix)(FixedSuffix)
        Return sb.ToString()
 
    End Function
 
End Class

' ***********************************************************************
' Author   : ElektroStudios
' Modified : 14-July-2023
' ***********************************************************************
 
#Region " Option Statements "
 
Option Strict On
Option Explicit On
Option Infer Off
 
#End Region
 
#Region " Imports "
 
#End Region
 
#Region " UtilPasswords "
 
' ReSharper disable once CheckNamespace
 
Namespace DevCase.Core.Security.Passwords
 
    ''' ----------------------------------------------------------------------------------------------------
    ''' <summary>
    ''' Represents the options for generating a memorable password 
    ''' with <see cref="UtilPasswords.GenerateMemorablePassword"/> function.
    ''' </summary>
    ''' ----------------------------------------------------------------------------------------------------
    Public Class MemorablePasswordOptions
 
#Region " Properties "
 
        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Gets or sets the number of words to include in the password.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        Public Property NumberOfWords As Integer
 
        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Gets or sets the minimum length of a word to consider for the password.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        Public Property MinimumWordLength As Integer
 
        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Gets or sets the maximum length of a word to consider for the password.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        Public Property MaximumWordLength As Integer
 
        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Gets or sets the characters to use as separators between words.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        Public Property SeparatorCharacters As Char()
 
        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Gets or sets the prefix to prepend to the password.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        Public Property FixedPrefix As String
 
        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Gets or sets the suffix to append to the password.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        Public Property FixedSuffix As String
 
        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Gets or sets the number of digits to include as a prefix to the password 
        ''' (after prepending <see cref="MemorablePasswordOptions.FixedPrefix"/>).
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        Public Property NumberOfDigitsPrefix As Integer
 
        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Gets or sets the number of digits to include as a suffix to the password 
        ''' (before appending <see cref="MemorablePasswordOptions.FixedSuffix"/>).
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        Public Property NumberOfDigitsSuffix As Integer
 
        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Gets or sets the case of the words in the password.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        Public Property StringCase As MemorablePasswordStringCase
 
#End Region
 
#Region " Constructors "
 
        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Initializes a new instance of the <see cref="MemorablePasswordOptions"/> class.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        Public Sub New()
        End Sub
 
#End Region
    End Class
 
End Namespace
 
#End Region
 

' ***********************************************************************
' Author   : ElektroStudios
' Modified : 14-July-2023
' ***********************************************************************
 
#Region " Option Statements "
 
Option Strict On
Option Explicit On
Option Infer Off
 
#End Region
 
#Region " Imports "
 
Imports DevCase.Core.DataProcessing.Common
 
#End Region
 
#Region " MemorablePasswordStringCase "
 
' ReSharper disable once CheckNamespace
 
Namespace DevCase.Core.Security.Passwords
 
    ''' <summary>
    ''' Specifies the string-case of the words in a memorable password.
    ''' </summary>
    Public Enum MemorablePasswordStringCase
 
        ''' <summary>
        ''' Changes all characters to lower-case.
        ''' <para></para>
        ''' 
        ''' [Example]
        ''' <para></para>
        ''' Input : ABCDEF
        ''' <para></para>
        ''' Output: abcdef
        ''' </summary>
        LowerCase = StringCase.LowerCase
 
        ''' <summary>
        ''' Changes all characters to upper-case.
        ''' <para></para>
        ''' 
        ''' [Example]
        ''' <para></para>
        ''' Input : abcdef
        ''' <para></para>
        ''' Output: ABCDEF
        ''' </summary>
        UpperCase = StringCase.UpperCase
 
        ''' <summary>
        ''' Changes the first characters to upper-case, 
        ''' and the rest of characters to lower-case.
        ''' <para></para>
        ''' 
        ''' [Example]
        ''' <para></para>
        ''' Input : abcdef
        ''' <para></para>
        ''' Output: Abcdef
        ''' </summary>
        TitleCase = StringCase.TitleCase
 
        ''' <summary>
        ''' Mixed-case with first character to lower-case.
        ''' <para></para>
        ''' 
        ''' [Example]
        ''' <para></para>
        ''' Input : ab cd ef
        ''' <para></para>
        ''' Output: aB Cd eF
        ''' </summary>
        MixedTitleCaseLower = StringCase.MixedTitleCaseLower
 
        ''' <summary>
        ''' Mixed-case with first character to upper-case.
        ''' <para></para>
        ''' 
        ''' [Example]
        ''' <para></para>
        ''' Input : ab cd ef
        ''' <para></para>
        ''' Output: Ab cD Ef
        ''' </summary>
        MixedTitleCaseUpper = StringCase.MixedTitleCaseUpper
 
        ''' <summary>
        ''' Toggle-case.
        ''' <para></para>
        ''' 
        ''' [Example]
        ''' <para></para>
        ''' Input : abc def ghi
        ''' <para></para>
        ''' Output: aBC dEF gHI
        ''' </summary>
        ToggleCase = StringCase.ToggleCase
 
        ''' <summary>
        ''' Alternates any lower-case character to upper-case and vice versa.
        ''' <para></para>
        ''' 
        ''' [Example]
        ''' <para></para>
        ''' Input : Hello World!
        ''' <para></para>
        ''' Output: hELLO wORLD!
        ''' </summary>
        AlternateChars = StringCase.AlternateChars
 
    End Enum
 
End Namespace
 
#End Region
 

' ***********************************************************************
' Author   : ElektroStudios
' Modified : 26-October-2015
' ***********************************************************************
 
#Region " Option Statements "
 
Option Strict On
Option Explicit On
Option Infer Off
 
#End Region
 
#Region " String Case "
 
' ReSharper disable once CheckNamespace
 
Namespace DevCase.Core.DataProcessing.Common
 
    ''' ----------------------------------------------------------------------------------------------------
    ''' <summary>
    ''' Specifies a string case.
    ''' </summary>
    ''' ----------------------------------------------------------------------------------------------------
    Public Enum StringCase As Integer
 
        ''' <summary>
        ''' LowerCase
        ''' <para></para>
        ''' 
        ''' [Example]
        ''' <para></para>
        ''' Input : ABCDEF
        ''' <para></para>
        ''' Output: abcdef
        ''' </summary>
        LowerCase = &H0
 
        ''' <summary>
        ''' UpperCase.
        ''' <para></para>
        ''' 
        ''' [Example]
        ''' <para></para>
        ''' Input : abcdef
        ''' <para></para>
        ''' Output: ABCDEF
        ''' </summary>
        UpperCase = &H1
 
        ''' <summary>
        ''' TitleCase.
        ''' <para></para>
        ''' 
        ''' [Example]
        ''' <para></para>
        ''' Input : abcdef
        ''' <para></para>
        ''' Output: Abcdef
        ''' </summary>
        TitleCase = &H2
 
        ''' <summary>
        ''' WordCase.
        ''' <para></para>
        ''' 
        ''' [Example]
        ''' <para></para>
        ''' Input : abc def
        ''' <para></para>
        ''' Output: Abc Def
        ''' </summary>
        WordCase = &H3
 
        ''' <summary>
        ''' CamelCase (With first letter to LowerCase).
        ''' <para></para>
        ''' 
        ''' [Example]
        ''' <para></para>
        ''' Input : ABC DEF
        ''' <para></para>
        ''' Output: abcDef
        ''' </summary>
        CamelCaseLower = &H4
 
        ''' <summary>
        ''' CamelCase (With first letter to UpperCase).
        ''' <para></para>
        ''' 
        ''' [Example]
        ''' <para></para>
        ''' Input : ABC DEF
        ''' <para></para>
        ''' Output: AbcDef
        ''' </summary>
        CamelCaseUpper = &H5
 
        ''' <summary>
        ''' MixedCase (With first letter to LowerCase).
        ''' <para></para>
        ''' 
        ''' [Example]
        ''' <para></para>
        ''' Input : ab cd ef
        ''' <para></para>
        ''' Output: aB Cd eF
        ''' </summary>
        MixedTitleCaseLower = &H6
 
        ''' <summary>
        ''' MixedCase (With first letter to UpperCase).
        ''' <para></para>
        ''' 
        ''' [Example]
        ''' <para></para>
        ''' Input : ab cd ef
        ''' <para></para>
        ''' Output: Ab cD Ef
        ''' </summary>
        MixedTitleCaseUpper = &H7
 
        ''' <summary>
        ''' MixedCase (With first letter of each word to LowerCase).
        ''' <para></para>
        ''' 
        ''' [Example]
        ''' <para></para>
        ''' Input : ab cd ef
        ''' <para></para>
        ''' Output: aB cD eF
        ''' </summary>
        MixedWordCaseLower = &H8
 
        ''' <summary>
        ''' MixedCase (With first letter of each word to UpperCase).
        ''' <para></para>
        ''' 
        ''' [Example]
        ''' <para></para>
        ''' Input : ab cd ef
        ''' <para></para>
        ''' Output: Ab Cd Ef
        ''' </summary>
        MixedWordCaseUpper = &H9
 
        ''' <summary>
        ''' ToggleCase.
        ''' <para></para>
        ''' 
        ''' [Example]
        ''' <para></para>
        ''' Input : abc def ghi
        ''' <para></para>
        ''' Output: aBC dEF gHI
        ''' </summary>
        ToggleCase = &H10
 
        ''' <summary>
        ''' Duplicates the characters.
        ''' <para></para>
        ''' 
        ''' [Example]
        ''' <para></para>
        ''' Input : Hello World!
        ''' <para></para>
        ''' Output: HHeelllloo  WWoorrlldd!!
        ''' </summary>
        DuplicateChars = &H11
 
        ''' <summary>
        ''' Alternates the characters.
        ''' <para></para>
        ''' 
        ''' [Example]
        ''' <para></para>
        ''' Input : Hello World!
        ''' <para></para>
        ''' Output: hELLO wORLD!
        ''' </summary>
        AlternateChars = &H12
 
    End Enum
 
End Namespace
 
#End Region
 

' ***********************************************************************
' Author   : ElektroStudios
' Modified : 13-July-2023
' ***********************************************************************
 
#Region " Public Members Summary "
 
' String.Rename(StringCase) As String
 
#End Region
 
#Region " Option Statements "
 
Option Strict On
Option Explicit On
Option Infer Off
 
#End Region
 
#Region " Imports "
 
Imports System.ComponentModel
Imports System.Globalization
Imports System.Runtime.CompilerServices
 
Imports DevCase.Core.DataProcessing.Common
 
#End Region
 
#Region " String Extensions "
 
' ReSharper disable once CheckNamespace
 
Namespace DevCase.Extensions.StringExtensions
 
    ''' ----------------------------------------------------------------------------------------------------
    ''' <summary>
    ''' Contains custom extension methods to use with a <see cref="String"/> type.
    ''' </summary>
    ''' ----------------------------------------------------------------------------------------------------
    <HideModuleName>
    Public Module StringExtensions
 
#Region " Public Extension Methods "
 
        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Renames a string to the specified StringCase.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <example> This is a code example.
        ''' <code language="VB.NET">
        ''' Dim str As String = "Hello World".Rename(StringCase.UpperCase)
        ''' 
        ''' MessageBox.Show(str)
        ''' </code>
        ''' </example>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="sender">
        ''' The source <see cref="String"/>.
        ''' </param>
        ''' 
        ''' <param name="stringCase">
        ''' The <see cref="StringCase"/>.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The renamed string.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        <Extension>
        <EditorBrowsable(EditorBrowsableState.Always)>
        Public Function Rename(sender As String,
                               stringCase As StringCase) As String
 
            Select Case stringCase
 
                Case StringCase.LowerCase
                    Return sender.ToLower
 
                Case StringCase.UpperCase
                    Return sender.ToUpper
 
                Case StringCase.TitleCase
                    Return $"{Char.ToUpper(sender.First())}{sender.Remove(0, 1).ToLower()}"
 
                Case StringCase.WordCase
                    Return CultureInfo.InvariantCulture.TextInfo.ToTitleCase(sender.ToLower())
 
                Case StringCase.CamelCaseLower
                    Return _
                        $"{Char.ToLower(sender.First())}{ _
                            CultureInfo.InvariantCulture.TextInfo.ToTitleCase(sender.ToLower()).
                                Replace(" "c, String.Empty).
                                Remove(0, 1)}"
 
                Case StringCase.CamelCaseUpper
                    Return _
                        $"{Char.ToUpper(sender.First())}{ _
                            CultureInfo.InvariantCulture.TextInfo.ToTitleCase(sender.ToLower()).
                                Replace(" "c, String.Empty).
                                Remove(0, 1)}"
 
                Case StringCase.MixedTitleCaseLower
                    Dim sb As New Global.System.Text.StringBuilder
                    For i As Integer = 0 To sender.Length - 1 Step 2
                        If Not (i + 1) >= sender.Length Then
                            sb.AppendFormat("{0}{1}", Char.ToLower(sender(i)), Char.ToUpper(sender(i + 1)))
                        Else
                            sb.Append(Char.ToLower(sender(i)))
                        End If
                    Next i
                    Return sb.ToString()
 
                Case StringCase.MixedTitleCaseUpper
                    Dim sb As New Global.System.Text.StringBuilder
                    For i As Integer = 0 To sender.Length - 1 Step 2
                        If Not (i + 1) >= sender.Length Then
                            sb.AppendFormat("{0}{1}", Char.ToUpper(sender(i)), Char.ToLower(sender(i + 1)))
                        Else
                            sb.Append(Char.ToUpper(sender(i)))
                        End If
                    Next i
                    Return sb.ToString()
 
                Case StringCase.MixedWordCaseLower
                    Dim sb As New Global.System.Text.StringBuilder
                    For Each word As String In sender.Split
                        sb.AppendFormat("{0} ", Rename(word, StringCase.MixedTitleCaseLower))
                    Next word
                    Return sb.ToString()
 
                Case StringCase.MixedWordCaseUpper
                    Dim sb As New Global.System.Text.StringBuilder
                    For Each word As String In sender.Split
                        sb.AppendFormat("{0} ", Rename(word, StringCase.MixedTitleCaseUpper))
                    Next word
                    Return sb.ToString()
 
                Case StringCase.ToggleCase
                    Dim sb As New Global.System.Text.StringBuilder
                    For Each word As String In sender.Split
                        sb.AppendFormat("{0}{1} ", Char.ToLower(word.First()), word.Remove(0, 1).ToUpper)
                    Next word
                    Return sb.ToString()
 
                Case StringCase.DuplicateChars
                    Dim sb As New Global.System.Text.StringBuilder
                    For Each c As Char In sender
                        sb.Append(New String(c, 2))
                    Next c
                    Return sb.ToString()
 
                Case StringCase.AlternateChars
                    Dim sb As New Global.System.Text.StringBuilder
                    For Each c As Char In sender
                        Select Case Char.IsLower(c)
                            Case True
                                sb.Append(Char.ToUpper(c))
                            Case Else
                                sb.Append(Char.ToLower(c))
                        End Select
                    Next c
                    Return sb.ToString()
 
                Case Else
                    Return sender
 
            End Select
 
        End Function
 
#End Region
 
    End Module
 
End Namespace
 
#End Region
 

' ***********************************************************************
' Author   : ElektroStudios
' Modified : 12-July-2023
' ***********************************************************************
 
#Region " Public Members Summary "
 
#Region " Functions "
 
' MaskSecureString(String, Opt: Char) As SecureString
' MaskSecureString(String, Char(), Opt: Char) As SecureString
' MaskSecureString(String, Integer, Boolean, Opt: Char) As SecureString
' MaskSecureString(String, Integer, Boolean, Char(), Opt: Char) As SecureString
 
' MaskSecureString(SecureString, Opt: Char) As SecureString
' MaskSecureString(SecureString, Char(), Opt: Char) As SecureString
' MaskSecureString(SecureString, Integer, Boolean, Opt: Char) As SecureString
' MaskSecureString(SecureString, Integer, Boolean, Char(), Opt: Char) As SecureString
 
#End Region
 
#End Region
 
#Region " Option Statements "
 
Option Strict On
Option Explicit On
Option Infer Off
 
#End Region
 
#Region " Imports "
 
Imports System.Text
Imports System.Security
Imports System.ComponentModel
Imports System.Runtime.InteropServices
Imports System.Collections.Generic
Imports System.Linq
 
#End Region
 
#Region " UtilPasswords "
 
' ReSharper disable once CheckNamespace
 
Namespace DevCase.Core.Security.Passwords
 
    Public NotInheritable Class UtilPasswords
 
#Region " Public Methods "
 
        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Masks the source string with a specific character.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <example> This is a code example.
        ''' <code language="VB.NET">
        ''' Dim password As String = "This is a password"
        ''' Dim maskChar As Char = "*"c
        ''' 
        ''' Dim masked As SecureString = MaskSecureString(password, maskChar)
        ''' </code>
        ''' </example>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="input">
        ''' The string to mask.
        ''' </param>
        ''' 
        ''' <param name="maskCharacter">
        ''' Optional. The character used for masking (default: "*").
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The masked string.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepperBoundary>
        Public Shared Function MaskSecureString(input As String, Optional maskCharacter As Char = "*"c) As SecureString
 
            Return MaskSecureString(input, maskLength:=input.Length, leftToRight:=True, allowedChars:=Nothing, maskCharacter)
 
        End Function
 
        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Masks the source string with a specific character, 
        ''' allowing certain characters to remain unmasked.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <example> This is a code example.
        ''' <code language="VB.NET">
        ''' Dim serialKey As String = "123-456-789"
        ''' Dim allowedChars As Char() = "-".ToCharArray()
        ''' Dim maskChar As Char = "*"c
        ''' 
        ''' Dim masked As SecureString = MaskSecureString(serialKey, allowedChars, maskChar)
        ''' </code>
        ''' </example>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="input">
        ''' The string to mask.
        ''' </param>
        ''' 
        ''' <param name="allowedChars">
        ''' An array of characters that are allowed to remain unmasked.
        ''' </param>
        ''' 
        ''' <param name="maskCharacter">
        ''' The character used for masking (default: "*").
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The masked string.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepperBoundary>
        Public Shared Function MaskSecureString(input As String, allowedChars As Char(), Optional maskCharacter As Char = "*"c) As SecureString
 
            Return MaskSecureString(input, maskLength:=input.Length, leftToRight:=True, allowedChars:=allowedChars, maskCharacter)
 
        End Function
 
        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Partially masks the source string with a specific character.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <example> This is a code example.
        ''' <code language="VB.NET">
        ''' Dim serialKey As String = "123-456-789"
        ''' Dim maskLength As Integer = 7
        ''' Dim leftToRight As Boolean = True
        ''' Dim maskChar As Char = "*"c
        ''' 
        ''' Dim masked As SecureString = MaskSecureString(serialKey, maskLength, leftToRight, maskChar)
        ''' </code>
        ''' </example>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="input">
        ''' The string to mask.
        ''' </param>
        ''' 
        ''' <param name="maskLength">
        ''' The length of the mask.
        ''' </param>
        ''' 
        ''' <param name="leftToRight">
        ''' Indicates the direction of the mask (left to right or right to left).
        ''' </param>
        ''' 
        ''' <param name="maskCharacter">
        ''' The character used for masking (default: "*").
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The masked string.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepperBoundary>
        Public Shared Function MaskSecureString(input As String, maskLength As Integer, leftToRight As Boolean, Optional maskCharacter As Char = "*"c) As SecureString
 
            Return MaskSecureString(input, maskLength:=maskLength, leftToRight:=leftToRight, allowedChars:=Nothing, maskCharacter)
 
        End Function
 
        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Partially masks the source string with a specific character, 
        ''' allowing certain characters to remain unmasked.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <example> This is a code example.
        ''' <code language="VB.NET">
        ''' Dim serialKey As String = "123-456-789"
        ''' Dim maskLength As Integer = 7
        ''' Dim leftToRight As Boolean = True
        ''' Dim allowedChars As Char() = "-".ToCharArray()
        ''' Dim maskChar As Char = "*"c
        ''' 
        ''' Dim masked As SecureString = MaskSecureString(serialKey, maskLength, leftToRight, allowedChars, maskChar)
        ''' </code>
        ''' </example>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="input">
        ''' The string to mask.
        ''' </param>
        ''' 
        ''' <param name="maskLength">
        ''' The length of the mask.
        ''' </param>
        ''' 
        ''' <param name="leftToRight">
        ''' Indicates the direction of the mask (left to right or right to left).
        ''' </param>
        ''' 
        ''' <param name="allowedChars">
        ''' An array of characters that are allowed to remain unmasked.
        ''' </param>
        ''' 
        ''' <param name="maskCharacter">
        ''' The character used for masking (default: "*").
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The masked string.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepperBoundary>
        Public Shared Function MaskSecureString(input As String, maskLength As Integer, leftToRight As Boolean, allowedChars As Char(), Optional maskCharacter As Char = "*"c) As SecureString
 
            If String.IsNullOrEmpty(input) Then
                Throw New ArgumentNullException(paramName:=NameOf(input))
            End If
 
            If String.IsNullOrEmpty(maskCharacter) Then
                Throw New ArgumentNullException(paramName:=NameOf(maskCharacter))
            End If
 
            If maskLength <= 0 Then
                Throw New ArgumentException($"maskLength must be greather than zero.", paramName:=NameOf(maskLength))
            End If
 
            Dim valueLength As Integer = input.Length
            If maskLength > valueLength Then
                Throw New ArgumentException($"maskLength can't be greather than the source string length.", paramName:=NameOf(maskLength))
            End If
 
            Dim allowedCharIndices As IDictionary(Of Integer, Char) = Nothing
            If allowedChars IsNot Nothing AndAlso allowedChars.Length > 0 Then
                allowedCharIndices = New Dictionary(Of Integer, Char)
                Dim startPos As Integer
                Dim endPos As Integer
 
                If maskLength = valueLength Then ' Full mask.
                    startPos = 0
                    endPos = valueLength - 1
                Else
                    If leftToRight Then ' Left to right mask.
                        startPos = 0
                        endPos = maskLength - 1
                    Else ' Right to left mask.
                        startPos = valueLength - maskLength
                        endPos = valueLength - 1
                    End If
                End If
 
                For i As Integer = startPos To endPos
                    Dim c As Char = input(i)
                    If allowedChars.Contains(c) Then
                        allowedCharIndices.Add(i, c)
                    End If
                Next
            End If
 
            Dim sec As New SecureString()
            If maskLength = valueLength Then ' Full mask.
                For i As Integer = 0 To valueLength
                    Dim dictValue As Char = Nothing
                    If allowedCharIndices IsNot Nothing AndAlso allowedCharIndices.TryGetValue(i, dictValue) Then
                        sec.AppendChar(dictValue)
                        Continue For
                    End If
                    sec.AppendChar(maskCharacter)
                Next
 
            Else
                If leftToRight Then ' Left to right mask.
                    For i As Integer = 0 To maskLength - 1
                        Dim dictValue As Char = Nothing
                        If allowedCharIndices IsNot Nothing AndAlso allowedCharIndices.TryGetValue(i, dictValue) Then
                            sec.AppendChar(dictValue)
                            Continue For
                        End If
                        sec.AppendChar(maskCharacter)
                    Next
                    For i As Integer = maskLength To valueLength - 1
                        sec.AppendChar(input(i))
                    Next
                Else ' Right to left mask.
                    For i As Integer = 0 To valueLength - maskLength - 1
                        sec.AppendChar(input(i))
                    Next
                    For i As Integer = valueLength - maskLength To valueLength - 1
                        Dim dictValue As Char = Nothing
                        If allowedCharIndices IsNot Nothing AndAlso allowedCharIndices.TryGetValue(i, dictValue) Then
                            sec.AppendChar(dictValue)
                            Continue For
                        End If
                        sec.AppendChar(maskCharacter)
                    Next
                End If
            End If
 
            Return sec
        End Function
 
        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Masks the source string with a specific character.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <example> This is a code example.
        ''' <code language="VB.NET">
        ''' Dim secureStr As New SecureString()
        ''' With secureStr
        '''     .AppendChar("p"c)
        '''     .AppendChar("a"c)
        '''     .AppendChar("s"c)
        '''     .AppendChar("s"c)
        '''     .AppendChar("w"c)
        '''     .AppendChar("o"c)
        '''     .AppendChar("r"c)
        '''     .AppendChar("d"c)
        ''' End With
        ''' 
        ''' Dim maskChar As Char = "*"c
        ''' Dim masked As SecureString = MaskSecureString(secureStr, maskChar)
        ''' </code>
        ''' </example>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="value">
        ''' The string to mask.
        ''' </param>
        ''' 
        ''' <param name="maskCharacter">
        ''' Optional. The character used for masking (default: "*").
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The masked string.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepperBoundary>
        Public Shared Function MaskSecureString(value As SecureString, Optional maskCharacter As Char = "*"c) As SecureString
 
            Return MaskSecureString(value, maskLength:=value.Length, leftToRight:=True, allowedChars:=Nothing, maskCharacter)
 
        End Function
 
        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Masks the source string with a specific character, 
        ''' allowing certain characters to remain unmasked.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <example> This is a code example.
        ''' <code language="VB.NET">
        ''' Dim serialKey As New SecureString()
        ''' With serialKey
        '''     .AppendChar("1"c)
        '''     .AppendChar("2"c)
        '''     .AppendChar("3"c)
        '''     .AppendChar("-"c)
        '''     .AppendChar("4"c)
        '''     .AppendChar("5"c)
        '''     .AppendChar("6"c)
        '''     .AppendChar("-"c)
        '''     .AppendChar("7"c)
        '''     .AppendChar("8"c)
        '''     .AppendChar("9"c)
        ''' End With
        ''' 
        ''' Dim allowedChars As Char() = "-".ToCharArray()
        ''' Dim maskChar As Char = "*"c
        ''' 
        ''' Dim masked As SecureString = MaskSecureString(serialKey, allowedChars, maskChar)
        ''' </code>
        ''' </example>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="value">
        ''' The string to mask.
        ''' </param>
        ''' 
        ''' <param name="allowedChars">
        ''' An array of characters that are allowed to remain unmasked.
        ''' </param>
        ''' 
        ''' <param name="maskCharacter">
        ''' The character used for masking (default: "*").
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The masked string.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepperBoundary>
        Public Shared Function MaskSecureString(value As SecureString, allowedChars As Char(), Optional maskCharacter As Char = "*"c) As SecureString
 
            Return MaskSecureString(value, maskLength:=value.Length, leftToRight:=True, allowedChars:=allowedChars, maskCharacter)
 
        End Function
 
        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Partially masks the source string with a specific character.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <example> This is a code example.
        ''' <code language="VB.NET">
        ''' Dim serialKey As New SecureString()
        ''' With serialKey
        '''     .AppendChar("1"c)
        '''     .AppendChar("2"c)
        '''     .AppendChar("3"c)
        '''     .AppendChar("-"c)
        '''     .AppendChar("4"c)
        '''     .AppendChar("5"c)
        '''     .AppendChar("6"c)
        '''     .AppendChar("-"c)
        '''     .AppendChar("7"c)
        '''     .AppendChar("8"c)
        '''     .AppendChar("9"c)
        ''' End With
        ''' 
        ''' Dim maskLength As Integer = 7
        ''' Dim leftToRight As Boolean = True
        ''' Dim maskChar As Char = "*"c
        ''' 
        ''' Dim masked As SecureString = MaskSecureString(serialKey, maskLength, leftToRight, maskChar)
        ''' </code>
        ''' </example>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="value">
        ''' The string to mask.
        ''' </param>
        ''' 
        ''' <param name="maskLength">
        ''' The length of the mask.
        ''' </param>
        ''' 
        ''' <param name="leftToRight">
        ''' Indicates the direction of the mask (left to right or right to left).
        ''' </param>
        ''' 
        ''' <param name="maskCharacter">
        ''' The character used for masking (default: "*").
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The masked string.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepperBoundary>
        Public Shared Function MaskSecureString(value As SecureString, maskLength As Integer, leftToRight As Boolean, Optional maskCharacter As Char = "*"c) As SecureString
 
            Return MaskSecureString(value, maskLength:=maskLength, leftToRight:=leftToRight, allowedChars:=Nothing, maskCharacter)
 
        End Function
 
        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Partially masks the source string with a specific character, 
        ''' allowing certain characters to remain unmasked.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <example> This is a code example.
        ''' <code language="VB.NET">
        ''' Dim serialKey As New SecureString()
        ''' With serialKey
        '''     .AppendChar("1"c)
        '''     .AppendChar("2"c)
        '''     .AppendChar("3"c)
        '''     .AppendChar("-"c)
        '''     .AppendChar("4"c)
        '''     .AppendChar("5"c)
        '''     .AppendChar("6"c)
        '''     .AppendChar("-"c)
        '''     .AppendChar("7"c)
        '''     .AppendChar("8"c)
        '''     .AppendChar("9"c)
        ''' End With
        ''' 
        ''' Dim maskLength As Integer = 7
        ''' Dim leftToRight As Boolean = True
        ''' Dim allowedChars As Char() = "-".ToCharArray()
        ''' Dim maskChar As Char = "*"c
        ''' 
        ''' Dim masked As SecureString = MaskSecureString(serialKey, maskLength, leftToRight, allowedChars, maskChar)
        ''' </code>
        ''' </example>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="value">
        ''' The string to mask.
        ''' </param>
        ''' 
        ''' <param name="maskLength">
        ''' The length of the mask.
        ''' </param>
        ''' 
        ''' <param name="leftToRight">
        ''' Indicates the direction of the mask (left to right or right to left).
        ''' </param>
        ''' 
        ''' <param name="allowedChars">
        ''' An array of characters that are allowed to remain unmasked.
        ''' </param>
        ''' 
        ''' <param name="maskCharacter">
        ''' The character used for masking (default: "*").
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The masked string.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepperBoundary>
        Public Shared Function MaskSecureString(value As SecureString, maskLength As Integer, leftToRight As Boolean, allowedChars As Char(), Optional maskCharacter As Char = "*"c) As SecureString
 
            Dim managedString As String = ToManagedString(value)
            Return MaskSecureString(managedString, maskLength:=maskLength, leftToRight:=leftToRight, allowedChars:=allowedChars, maskCharacter:=maskCharacter)
 
        End Function
 
#End Region
 
#Region " Private Methods "
 
        ''' ----------------------------------------------------------------------------------------------------
        ''' <summary>
        ''' Converts the source <see cref="Global.System.Security.SecureString"/> to a managed <see cref="String"/>.
        ''' </summary>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <example> This is a code example.
        ''' <code language="VB.NET">
        ''' Dim secStr As New SecureString()
        ''' With secStr
        '''     .AppendChar("q"c)
        '''     .AppendChar("w"c)
        '''     .AppendChar("e"c)
        '''     .AppendChar("r"c)
        '''     .AppendChar("t"c)
        '''     .AppendChar("y"c)
        ''' End With
        ''' 
        ''' MessageBox.Show(secStr.ToManagedString())
        ''' </code>
        ''' </example>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <param name="secureString">
        ''' The source <see cref="Global.System.Security.SecureString"/>.
        ''' </param>
        ''' ----------------------------------------------------------------------------------------------------
        ''' <returns>
        ''' The resulting <see cref="String"/>.
        ''' </returns>
        ''' ----------------------------------------------------------------------------------------------------
        <DebuggerStepThrough>
        <EditorBrowsable(EditorBrowsableState.Never)>
        Private Shared Function ToManagedString(secureString As Global.System.Security.SecureString) As String
 
            If secureString Is Nothing Then
                Throw New ArgumentNullException(NameOf(secureString))
            End If
 
            If secureString.Length = 0 Then
                Return ""
 
            Else
                Dim ptr As System.IntPtr = Global.System.IntPtr.Zero
 
                Try
                    ptr = Marshal.SecureStringToGlobalAllocUnicode(secureString)
                    Return Marshal.PtrToStringUni(ptr)
 
                Finally
                    If ptr <> IntPtr.Zero Then
                        Marshal.ZeroFreeGlobalAllocUnicode(ptr)
                    End If
 
                End Try
 
            End If
 
        End Function
 
#End Region
 
    End Class
 
End Namespace
 
#End Region