Multipurpose Batch Substring String Modification Function

@Echo Off & Mode 1000

:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Mod-string Function By T3RRY
:::
::: Multi-Purpose String Modification Function with various options to suit a range of needs.
:::
::: For use On Windows 10 in Scripts that need to process Large volumes of Strings and Find, Append, Remove, Or Modify Known Substrings.
:::
:::  Note: This Function Is for String / SubString Modification in defined variables.
:::
::: Ensure Substring targeted for Modification is Unique in the String.
::: Case Sensitive to limit False positives.
::: Doublequote Strings containing Spaces or Special Characters
:::
::: REM All Switches return a string length result in the variable StringLen
:::
::: REM if the folder containing modstring is in your system PATH variable, type modstring in cmd.exe to see the Syntax.


:ModString REM Usage - ModString <stringVar> <SubString> </Switch> </XS,/IB,/IA only: "New Substring">

::::: SWITCHES:
::: - Function must be called with ONLY ONE of the following Switches to define the Modification Type.
:::
::: /AR removes everything AFTER  the substring, REMOVES the Substring.
::: /AK removes everything AFTER  the substring,   KEEPS the Substring.
::: /BR removes everything BEFORE the substring, REMOVES the Substring.
::: /BK removes everything BEFORE the substring,   KEEPS the Substring.
::: /RS REMOVES the SUBSTRING from the string.
::: /XS EXCHANGES the SUBSTRING with new substring Defined in Parameter 4.
::: /IB INSERTS new substring Defined in Parameter 4 BEFORE the substring.
::: /IA INSERTS new substring Defined in Parameter 4  AFTER the substring.
::: /DS adds a DATE time SUFFIX to the STRING
::: /DP adds a DATE time PREFIX to the STRING
::: /FS FIND SUBSTRING in string. Does Not Modify the String. True or False value stored in the Variable: Str_Find

    Setlocal EnableDelayedExpansion

::: Test Parameters 1 2 and 3 for definition. Displays Syntax if Parameters are not Defined.

    IF "%~1"=="" CALL :MS_Syntax 1
    IF "!%~1!"=="" CALL :MS_Syntax 1b
    IF "%~2"=="" CALL :MS_Syntax 2
    IF "%~3"=="" CALL :MS_syntax 3 Missing

    IF Defined ParamError (
        ECHO  & REM The preceeding Character is the BEL character, Not the ANSI ESC character used for Color Codes.
        ECHO(Exit
        pause >nul
        Cls
        Exit /B 1
    )

::: Store the Value of the String from the Source Variable into tmpStr Variable

    Set "tmpStr=!%~1!"

::: Modify the Switch for Conditional Validation.

    Set "Switch=%~3"
    Set "Switch=!Switch:/=!"
    Set "Switch=!Switch:\=!"

::: Test definition of Fourth Parameter for Relevent Switches.

    FOR %%F IN (XS,IA,IB) Do (
        If /I "%%F"=="!Switch!" (
            IF "%~4"=="" (
                ECHO  & REM The preceeding Character is the BEL character, Not the ANSI ESC character used for Color Codes.
                CALL :MS_Syntax 4
                ECHO(Exit
                pause >nul
                Cls
                Exit /B 1
            )
        )
    )

::: Get Length of Substring and String for Use in Substring Modification Functions

    Call :StrLen Len "%~2"
    CALL :StrLen FullLen "!%~1!"
    IF Errorlevel 1 (
        ECHO  & REM The preceeding Character is the BEL character, Not the ANSI ESC character used for Color Codes.
        CALL :MS_Syntax 5 "Variable content exceeds maximum Length"
        ECHO(Exit
        pause >nul
        Exit /B 1
    )

::: Test Value of Parameter 3 /Switch for Valid Switch, Progress to relevent Function if True, Display Syntax Help if Not.

    FOR %%S IN (AR,AK,BR,BK,RS,XS,IA,IB,FS,DS,DP) Do (
        IF /I "!Switch!"=="%%S" (GOTO :MS_Switch_%%S)
    )

    ECHO  & REM The preceeding Character is the BEL character, Not the ANSI ESC character used for Color Codes.
    CALL :MS_Syntax 3 "Invalid Switch"
    ECHO(Exit
    pause >nul
    Exit /B 1

:StrLen REM Usage: <ResultVar> <StringVar>

    Setlocal EnableDelayedExpansion

    Set "tmpLen=%~2"

    For /L %%L in (1,1,500) Do (
        Set "LenTrim=!tmpLen:~0,-%%L!"
        If "!LenTrim!"=="" (
            Endlocal & Set "%~1=%%L"
            Exit /b 0
        )
    )

REM Limited to 500 Characters to Improve Function Speed.
    ECHO( Substring Exceeds Maximum Length (500 Characters)
    Endlocal
    Exit /B 1

:MS_Switch_DP
:MS_Switch_DS

    Set "appendDT=%DATE%"
    Set "appendDT=%appendDT: =%"
    Set "appendDT=%appendDT%%TIME%"
    Set "appendDT=%appendDT:/=%"
    Set "appendDT=%appendDT::=%"
    Set "appendDT=%appendDT:.=%"
    Set "appendDT=%appendDT: =0%"
    Set "appendDT=%appendDT:~3,12%"
    IF "%switch%"=="DP" (Set "tmpStr=%appendDT%%~2") Else (Set "tmpStr=%~2%appendDT%")
    GOTO :MS_Set

:MS_Switch_RS

    Set "tmpStr=!tmpStr:%~2=!"
    GOTO :MS_Set

:MS_Switch_XS

    Set "tmpStr=!tmpStr:%~2=%~4!"
    GOTO :MS_Set

:MS_Switch_IB

    Set "tmpStr=!tmpStr:%~2=%~4%~2!"
    GOTO :MS_Set

:MS_Switch_IA

    Set "tmpStr=!tmpStr:%~2=%~2%~4!"
    GOTO :MS_Set

::: The below switch subroutines all Assign a False value to the str_Find Variable if the String Does Not Contain the Substring
::: and a True value if the String contains the Substring.
::: MS_Switch_FS is the only subroutine that Does not Modify the original String in doing So.

REM The Following subroutines are all Case Sensitive to Ensure Exact Match. If case Insensitivity is required, Change:
REM (cont)  `IF "!ModStr!"=="%~2"` TO `IF /I "!ModStr!"=="%~2"`

:MS_Switch_FS

    For /L %%S in (0,1,!FullLen!) DO (
        Set "ModStr=!tmpStr:~%%S,%Len%!"
        IF "!ModStr!"=="%~2" (
            ECHO(%~2 Found in %tmpStr%
            GOTO :MS_Set
        )
    )
    GOTO :MS_SubFalse

:MS_Switch_BK

    For /L %%S in (0,1,!FullLen!) DO (
        Set "ModStr=!tmpStr:~%%S,%Len%!"
        IF "!ModStr!"=="%~2" (
            Set "tmpStr=!tmpStr:~0,%%S!%~2"
            GOTO :MS_Set
        )
    )
    GOTO :MS_SubFalse

:MS_Switch_BR

    For /L %%S in (0,1,!FullLen!) DO (
        Set "ModStr=!tmpStr:~%%S,%Len%!"
        IF "!ModStr!"=="%~2" (
            Set "tmpStr=!tmpStr:~0,%%S!"
            GOTO :MS_Set
        )
    )
    GOTO :MS_SubFalse

:MS_Switch_AR

    For /L %%S in (0,1,!FullLen!) DO (
        Set "ModStr=!tmpStr:~%%S,%Len%!"
        IF "!ModStr!"=="%~2" (
            Set "tmpStr=!tmpStr:~%%S,%FullLen%!"
            Set "tmpStr=!tmpStr:~%Len%,%FullLen%!"
            GOTO :MS_Set
        )
    )
    GOTO :MS_SubFalse

:MS_Switch_AK

    For /L %%S in (0,1,!FullLen!) DO (
        Set "ModStr=!tmpStr:~%%S,%Len%!"
        IF "!ModStr!"=="%~2" (
            Set "tmpStr=!tmpStr:~%%S,%FullLen%!"
            GOTO :MS_Set
        )
    )
    GOTO :MS_SubFalse

::: On Success of Switch subroutines.

:MS_Set

    (
    ENDLOCAL
        FOR %%T IN (AR,AK,BR,BK,FS) DO (
            IF /I "%switch%"=="%%T" (
                Set "Str_Find=True"
            )
        )
    Set "%~1=%tmpStr%"
    Echo(%tmpStr%
    Set Len=%Len%
    Set StringLen=%FullLen%
    Exit /b 0
    )

::: On Not Encountering the Targeted Substring in the String during /FS /AR /AK /BR /BK Switch subroutines.
::: If the targeted substring is not found, No Modification Will be Performed.

:MS_SubFalse

    (
    ECHO(%~2 Not Found in %tmpStr%
    ENDLOCAL
    Set "Str_Find=False"
    Set Len=%Len%
    Set StringLen=%FullLen%
    Exit /b 1
    )

REM ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ModString Function Syntax

:MS_Syntax
    ECHO(
    ECHO(ModString Syntax:
    ECHO(
    Set "ParamError=true"

    IF "%~1"=="1" (
        ECHO( Paramater 1 Missing. Must contain the Variable Name. For Use within a For Loop, Use
        ECHO( 'Setlocal EnableDelayedExpansionm' prior to the Loop and Set the Loop Variable to an Indexed Variable IE:
        ECHO(
        ECHO(  Set /a "_i+=1"
        ECHO(  Set "Var[^!_i^!]=%%%%A"
        ECHO(
        ECHO( And use ModString as Follows :
        ECHO( If ModString is a subroutine   - CALL :ModString "Var[^!_i^!]" Substring /Switch
        ECHO( If ModString is a .bat program - CALL C:\Your\File\Path\ModString.bat "Var[^!_i^!]" Substring /Switch
        ECHO( If ModString is a .bat program and the path loaction is stored in your System Environment Path Variable :
        ECHO( ModString "Var[^!_i^!]" Substring /Switch
        exit /b
    )

    IF "%~1"=="1b" (
        ECHO( Paramater 1 Variable is not Defined. Variable must be set with a value prior to using ModString
        exit /b
    )

    IF "%~1"=="2" (
        ECHO( Paramater 2 Missing. Must contain the target Substring  Ie: _2020
        exit /b
    )

    IF "%~1"=="3" (
        ECHO( Parameter 3 - %~2. Must Contain A valid Switch to select substring modification type.
        ECHO(  Valid Switches are:
        ECHO(
        ECHO(   /AR REMOVES   everything  AFTER the Substring, REMOVES the Substring.
        ECHO(   /AK REMOVES   everything  AFTER the Substring,   KEEPS the Substring.
        ECHO(   /BR REMOVES   everything BEFORE the Substring, REMOVES the Substring.
        ECHO(   /BK REMOVES   everything BEFORE the Substring,   KEEPS the Substring.
        ECHO(   /RS REMOVES   the SUBSTRING from the string.
        ECHO(   /XS EXCHANGES the SUBSTRING with the Substring Defined in Parameter 4.
        ECHO(   /IB INSERTS   new substring Defined in Parameter 4 BEFORE the substring.
        ECHO(   /IA INSERTS   new substring Defined in Parameter 4  AFTER the substring.
        ECHO(   /DS adds a DATE time SUFFIX to the STRING
        ECHO(   /DP adds a DATE time PREFIX to the STRING
        ECHO(   /FS FIND SUBSTRING in string. True / False value stored in the Variable: Str_Find
        exit /b
    )

    IF "%~1"=="4" (
        ECHO(
        ECHO( Parameter 4 Must be Defined with a String to Insert when using the /!switch!  switch.
        ECHO(  Example:
        ECHO(
        ECHO( CALL :ModString VarName "targetstring" /!Switch! "newstring"
        ECHO(
        exit /b
        )

    IF "%~1"=="5" (
        ECHO(
        ECHO(  %~2.
        ECHO( Default Limit is 500 characters.Adjust limit in StringLength subroutine if required.
        ECHO(
    )



:::
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: End Mod-String Function