AntGut/Indent-String.ps1

## Indent-String.ps1
<#
.SYNOPSIS
    Indents/PadLeft an InputString a specified amount (using specified char) and PadRight (with a specified char) if necessary to make output string the specified total length.

.DESCRIPTION
    -- All PadLeft/PadRight constraints are adhered to.
    -- By default if "IndentCount + InputString.Length() > TotalLength", Indent/PadLeft will take precedence [return string will be longer than TotalLength].
       This behavior can be overridden using "UseTotalLength".
    -- Default padding character is a <space> which can be overridden.

.PARAMETER InputString
    String to be indented and right-padded.

.PARAMETER IndentCount
    How many characters to indent (PadLeft).
    Anything but a whole number >= 0 will default to 0.

.PARAMETER TotalLength
    Total length of output string; also considered maximum length.
    Anything but a whole number >= 0 will default to 0.
    If left-padded string is < TotalLength, the string will be right-padded with PadRightChar.

.PARAMETER PadLeftChar
    Character to use for indenting/left-padding.
    Default is <space>.
    Empty and $null values are replaced with <space>.

.PARAMETER PadRightChar
    Character to use for right-padding.
    Default is <space>.
    Empty and $null values are replaced with <space>.

.PARAMETER UseTotalLength
    When specified and "IndentCount + InputString.Length() > TotalLength", the LeftPad for the output string is "shortened" so the output string meets the TotalLength requirement (maximum length).
    useful for when IndentCount and TotalLength aren't known, but want to control the output using TotalLength.
    Note: If InputString.Length() > TotalLength, the string will be returned "as-is"; no leading characters are ever removed to meet TotalLength requirement.

.EXAMPLE
    # Snippet to demonstrate default behavior (indent takes priority over total/maximum length).
    $TabSize = 4
    $MaxLen = 30
    for ($i = 0; $i -le 9; $i++) {
        $Indent = $TabSize*$i
        (Indent-String "Level $i" $Indent $MaxLen) + ": $Indent $MaxLen"
    }

    Level 0                       : 0 30
        Level 1                   : 4 30
            Level 2               : 8 30
                Level 3           : 12 30
                    Level 4       : 16 30
                        Level 5   : 20 30
                            Level 6: 24 30
                                Level 7: 28 30
                                    Level 8: 32 30
                                        Level 9: 36 30
.EXAMPLE
    # Same as above, except specifying " " for LeftPadChar and "." for RightPadChar.
    $TabSize = 4
    $MaxLen = 30
    for ($i = 0; $i -le 9; $i++) {
        $Indent = $TabSize*$i
        (Indent-String "Level $i" $Indent $MaxLen " " ".") + ": $Indent $MaxLen "" "" ""."""
    }

    Level 0.......................: 0 30 " " "."
        Level 1...................: 4 30 " " "."
            Level 2...............: 8 30 " " "."
                Level 3...........: 12 30 " " "."
                    Level 4.......: 16 30 " " "."
                        Level 5...: 20 30 " " "."
                            Level 6: 24 30 " " "."
                                Level 7: 28 30 " " "."
                                    Level 8: 32 30 " " "."
                                        Level 9: 36 30 " " "."

.EXAMPLE
    # Same as above, except using "-UseTotalLength" to enforce total/maximum length restrictions.
    $TabSize = 4
    $MaxLen = 30
    for ($i = 0; $i -le 9; $i++) {
        $Indent = $TabSize*$i
        (Indent-String "Level $i" $Indent $MaxLen " " "." -UseTotalLength) + ": $Indent $MaxLen "" "" ""."" -UseTotalLength"
    }

    Level 0.......................: 0 30 " " "." -UseTotalLength
        Level 1...................: 4 30 " " "." -UseTotalLength
            Level 2...............: 8 30 " " "." -UseTotalLength
                Level 3...........: 12 30 " " "." -UseTotalLength
                    Level 4.......: 16 30 " " "." -UseTotalLength
                        Level 5...: 20 30 " " "." -UseTotalLength
                           Level 6: 24 30 " " "." -UseTotalLength
                           Level 7: 28 30 " " "." -UseTotalLength
                           Level 8: 32 30 " " "." -UseTotalLength
                           Level 9: 36 30 " " "." -UseTotalLength

.NOTES
--==--==--==--==--==--==--==--== DISCLAIMER ==--==--==--==--==--==--==--==--
This Sample Code is provided for the purpose of illustration only and is not intended to be used in a production environment.
THIS SAMPLE CODE AND ANY RELATED INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
We grant you a nonexclusive, royalty-free right to use and modify the sample code and to reproduce and distribute the object
code form of the Sample Code, provided that you agree:
    (i)   to not use our name, logo, or trademarks to market your software product in which the sample code is embedded;
    (ii)  to include a valid copyright notice on your software product in which the sample code is embedded; and
    (iii) to indemnify, hold harmless, and defend us and our suppliers from and against any claims or lawsuits, including
          attorneys' fees, that arise or result from the use or distribution of the sample code.
Please note: None of the conditions outlined in the disclaimer above will supercede the terms and conditions contained within
the Premier Customer Services Description.

--==--==--==--==--==
Version History
--==--==--==--==--==
20180927.0: Anthony 'AntGut' F. Gutierrez (Sr. PFE)
    Initial write-up.
20181003.0: Anthony 'AntGut' F. Gutierrez (Sr. PFE)
    Add ability to use non-whitespace char for PadLeft & PadRight.
#>

function Indent-String () {
#--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==

    Param (
        [string]$InputString,
        [int]$IndentCount,
        [int]$TotalLength,
        [string]$PadLeftChar,
        [string]$PadRightChar,
        [switch]$UseTotalLength = $False
    )

    # Accomodate for bad input values. If not a positive integer, set to zero!
    if ($IndentCount -notmatch '^\d+$') {$IndentCount = 0}
    if ($TotalLength -notmatch '^\d+$') {$TotalLength = 0}

    # Accomodate for bad input values. If pad chars are empty or $null, default to <space>.
    # 2018-10-03, AntGut: Need to add better validation; like checking that these are printable!!!
    if (-not($PadLeftChar)) {$PadLeftChar = " "}
    if (-not($PadRightChar)) {$PadRightChar = " "}

    # Check if inbond string is empty or $null.
    # If IndentCount = 0 and TotalLength = 0, just return an empty string. Otherwise prep for returning an "all white space" string.
    if (-not($InputString)) {
        if ($IndentCount -eq 0 -and $TotalLength -eq 0) {
            return ""
        }
        $InputString = " "
    }

    # Reduce Indent/PadLeft count if necessary
    if ($UseTotalLength) {
        if ($IndentCount + $InputString.Length -gt $TotalLength) {
            $IndentCount = $TotalLength - $InputString.Length
        }
    }

    # Build indentation; not a very good method, but it works!
    $Indent = ""
    if ($IndentCount -gt 0) {
        foreach ($i in 1..$IndentCount) {
            $Indent += $PadLeftChar
        }
    }

    # Really, this could be in the above loop!
    $IndentedString = $Indent + $InputString

    return ($IndentedString).PadRight($TotalLength, $PadRightChar)
}

#--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==
function Test-String ($TestString) {
#--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==
    (Indent-String $TestString 0 0) + ": 0 0"
    (Indent-String $TestString 0 0 -UseTotalLength) + ": 0 0 -UseTotalLength"
    (Indent-String $TestString 0 30 "" ".") + ": 0 30"
    (Indent-String $TestString 0 30 -UseTotalLength "." ".") + ": 0 30 -UseTotalLength"
    (Indent-String $TestString 30 30) + ": 30 30"
    (Indent-String $TestString 30 30 -UseTotalLength) + ": 30 30 -UseTotalLength"
    (Indent-String $TestString 30 40 "" ".") + ": 30 40"
    (Indent-String $TestString 30 40 -UseTotalLength "" ".") + ": 30 40 -UseTotalLength"
    (Indent-String $TestString 40 30) + ": 40 30"
    (Indent-String $TestString 40 30 -UseTotalLength) + ": 40 30 -UseTotalLength"
    (Indent-String $TestString 30 0) + ": 30 0"
    (Indent-String $TestString 30 0 -UseTotalLength) + ": 30 0 -UseTotalLength"
}

#--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==
function Test-Cases () {
#--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==
    $LongLine = '--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--=='
    $columnCount = '123456789 123456789 123456789 123456789 123456789 123456789'

    $LongLine
    Write-Host "InputString is empty """""
    $columnCount
    Test-It ""
    Write-Host

    $LongLine
    Write-Host "InputString is null"
    $columnCount
    Test-It $null
    Write-Host

    $LongLine
    Write-Host "InputString is a single space"
    $columnCount
    Test-It " "
    Write-Host

    $LongLine
    Write-Host "InputString is a single char (x)"
    $columnCount
    Test-It "X"
    Write-Host
}

<#
.SYNOPSIS
    Just shows a couple of examples of using Indent-String.
#>
function Show-Examples () {
#--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==
    Write-Host "Loop showing default behavior."
    $TabSize = 4
    $MaxLen = 0
    for ($i = 0; $i -le 9; $i++) {
        $Indent = $TabSize*$i
        (Indent-String "Level $i" $Indent $MaxLen) + ": $Indent $MaxLen"
    }
    Write-Host

    Write-Host "Same as above, except using ""-UseTotalLength"". Note that using ""0"" for TotalLength is not good."
    $TabSize = 4
    $MaxLen = 0
    for ($i = 0; $i -le 9; $i++) {
        $Indent = $TabSize*$i
        (Indent-String "Level $i" $Indent $MaxLen -UseTotalLength) + ": $Indent $MaxLen -UseTotalLength"
    }
    Write-Host

    Write-Host "Loop showing default behavior with a ""better"" value for ""TotalLength""."
    $TabSize = 4
    $MaxLen = 30
    for ($i = 0; $i -le 9; $i++) {
        $Indent = $TabSize*$i
        (Indent-String "Level $i" $Indent $MaxLen) + ": $Indent $MaxLen"
    }
    Write-Host

    Write-Host "Same as above, except specifying "" "" for LeftPadChar and ""."" for RightPadChar."
    $TabSize = 4
    $MaxLen = 30
    for ($i = 0; $i -le 9; $i++) {
        $Indent = $TabSize*$i
        (Indent-String "Level $i" $Indent $MaxLen " " ".") + ": $Indent $MaxLen "" "" ""."""
    }
    Write-Host

    Write-Host "Same as above, except using ""-UseTotalLength""."
    $TabSize = 4
    $MaxLen = 30
    for ($i = 0; $i -le 9; $i++) {
        $Indent = $TabSize*$i
        (Indent-String "Level $i" $Indent $MaxLen " " "." -UseTotalLength) + ": $Indent $MaxLen "" "" ""."" -UseTotalLength"
    }

}
	<#
	.SYNOPSIS
	Indents/PadLeft an InputString a specified amount (using specified char) and PadRight (with a specified char) if necessary to make output string the specified total length.

	.DESCRIPTION
	-- All PadLeft/PadRight constraints are adhered to.
	-- By default if "IndentCount + InputString.Length() > TotalLength", Indent/PadLeft will take precedence [return string will be longer than TotalLength].
	This behavior can be overridden using "UseTotalLength".
	-- Default padding character is a <space> which can be overridden.

	.PARAMETER InputString
	String to be indented and right-padded.

	.PARAMETER IndentCount
	How many characters to indent (PadLeft).
	Anything but a whole number >= 0 will default to 0.

	.PARAMETER TotalLength
	Total length of output string; also considered maximum length.
	Anything but a whole number >= 0 will default to 0.
	If left-padded string is < TotalLength, the string will be right-padded with PadRightChar.

	.PARAMETER PadLeftChar
	Character to use for indenting/left-padding.
	Default is <space>.
	Empty and $null values are replaced with <space>.

	.PARAMETER PadRightChar
	Character to use for right-padding.
	Default is <space>.
	Empty and $null values are replaced with <space>.

	.PARAMETER UseTotalLength
	When specified and "IndentCount + InputString.Length() > TotalLength", the LeftPad for the output string is "shortened" so the output string meets the TotalLength requirement (maximum length).
	useful for when IndentCount and TotalLength aren't known, but want to control the output using TotalLength.
	Note: If InputString.Length() > TotalLength, the string will be returned "as-is"; no leading characters are ever removed to meet TotalLength requirement.

	.EXAMPLE
	# Snippet to demonstrate default behavior (indent takes priority over total/maximum length).
	$TabSize = 4
	$MaxLen = 30
	for ($i = 0; $i -le 9; $i++) {
	$Indent = $TabSize*$i
	(Indent-String "Level $i" $Indent $MaxLen) + ": $Indent $MaxLen"
	}

	Level 0 : 0 30
	Level 1 : 4 30
	Level 2 : 8 30
	Level 3 : 12 30
	Level 4 : 16 30
	Level 5 : 20 30
	Level 6: 24 30
	Level 7: 28 30
	Level 8: 32 30
	Level 9: 36 30
	.EXAMPLE
	# Same as above, except specifying " " for LeftPadChar and "." for RightPadChar.
	$TabSize = 4
	$MaxLen = 30
	for ($i = 0; $i -le 9; $i++) {
	$Indent = $TabSize*$i
	(Indent-String "Level $i" $Indent $MaxLen " " ".") + ": $Indent $MaxLen "" "" ""."""
	}

	Level 0.......................: 0 30 " " "."
	Level 1...................: 4 30 " " "."
	Level 2...............: 8 30 " " "."
	Level 3...........: 12 30 " " "."
	Level 4.......: 16 30 " " "."
	Level 5...: 20 30 " " "."
	Level 6: 24 30 " " "."
	Level 7: 28 30 " " "."
	Level 8: 32 30 " " "."
	Level 9: 36 30 " " "."

	.EXAMPLE
	# Same as above, except using "-UseTotalLength" to enforce total/maximum length restrictions.
	$TabSize = 4
	$MaxLen = 30
	for ($i = 0; $i -le 9; $i++) {
	$Indent = $TabSize*$i
	(Indent-String "Level $i" $Indent $MaxLen " " "." -UseTotalLength) + ": $Indent $MaxLen "" "" ""."" -UseTotalLength"
	}

	Level 0.......................: 0 30 " " "." -UseTotalLength
	Level 1...................: 4 30 " " "." -UseTotalLength
	Level 2...............: 8 30 " " "." -UseTotalLength
	Level 3...........: 12 30 " " "." -UseTotalLength
	Level 4.......: 16 30 " " "." -UseTotalLength
	Level 5...: 20 30 " " "." -UseTotalLength
	Level 6: 24 30 " " "." -UseTotalLength
	Level 7: 28 30 " " "." -UseTotalLength
	Level 8: 32 30 " " "." -UseTotalLength
	Level 9: 36 30 " " "." -UseTotalLength

	.NOTES
	--==--==--==--==--==--==--==--== DISCLAIMER ==--==--==--==--==--==--==--==--
	This Sample Code is provided for the purpose of illustration only and is not intended to be used in a production environment.
	THIS SAMPLE CODE AND ANY RELATED INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
	INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
	We grant you a nonexclusive, royalty-free right to use and modify the sample code and to reproduce and distribute the object
	code form of the Sample Code, provided that you agree:
	(i) to not use our name, logo, or trademarks to market your software product in which the sample code is embedded;
	(ii) to include a valid copyright notice on your software product in which the sample code is embedded; and
	(iii) to indemnify, hold harmless, and defend us and our suppliers from and against any claims or lawsuits, including
	attorneys' fees, that arise or result from the use or distribution of the sample code.
	Please note: None of the conditions outlined in the disclaimer above will supercede the terms and conditions contained within
	the Premier Customer Services Description.

	--==--==--==--==--==
	Version History
	--==--==--==--==--==
	20180927.0: Anthony 'AntGut' F. Gutierrez (Sr. PFE)
	Initial write-up.
	20181003.0: Anthony 'AntGut' F. Gutierrez (Sr. PFE)
	Add ability to use non-whitespace char for PadLeft & PadRight.
	#>

	function Indent-String () {
	#--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==

	Param (
	[string]$InputString,
	[int]$IndentCount,
	[int]$TotalLength,
	[string]$PadLeftChar,
	[string]$PadRightChar,
	[switch]$UseTotalLength = $False
	)

	# Accomodate for bad input values. If not a positive integer, set to zero!
	if ($IndentCount -notmatch '^\d+$') {$IndentCount = 0}
	if ($TotalLength -notmatch '^\d+$') {$TotalLength = 0}

	# Accomodate for bad input values. If pad chars are empty or $null, default to <space>.
	# 2018-10-03, AntGut: Need to add better validation; like checking that these are printable!!!
	if (-not($PadLeftChar)) {$PadLeftChar = " "}
	if (-not($PadRightChar)) {$PadRightChar = " "}

	# Check if inbond string is empty or $null.
	# If IndentCount = 0 and TotalLength = 0, just return an empty string. Otherwise prep for returning an "all white space" string.
	if (-not($InputString)) {
	if ($IndentCount -eq 0 -and $TotalLength -eq 0) {
	return ""
	}
	$InputString = " "
	}

	# Reduce Indent/PadLeft count if necessary
	if ($UseTotalLength) {
	if ($IndentCount + $InputString.Length -gt $TotalLength) {
	$IndentCount = $TotalLength - $InputString.Length
	}
	}

	# Build indentation; not a very good method, but it works!
	$Indent = ""
	if ($IndentCount -gt 0) {
	foreach ($i in 1..$IndentCount) {
	$Indent += $PadLeftChar
	}
	}

	# Really, this could be in the above loop!
	$IndentedString = $Indent + $InputString

	return ($IndentedString).PadRight($TotalLength, $PadRightChar)
	}

	#--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==
	function Test-String ($TestString) {
	#--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==
	(Indent-String $TestString 0 0) + ": 0 0"
	(Indent-String $TestString 0 0 -UseTotalLength) + ": 0 0 -UseTotalLength"
	(Indent-String $TestString 0 30 "" ".") + ": 0 30"
	(Indent-String $TestString 0 30 -UseTotalLength "." ".") + ": 0 30 -UseTotalLength"
	(Indent-String $TestString 30 30) + ": 30 30"
	(Indent-String $TestString 30 30 -UseTotalLength) + ": 30 30 -UseTotalLength"
	(Indent-String $TestString 30 40 "" ".") + ": 30 40"
	(Indent-String $TestString 30 40 -UseTotalLength "" ".") + ": 30 40 -UseTotalLength"
	(Indent-String $TestString 40 30) + ": 40 30"
	(Indent-String $TestString 40 30 -UseTotalLength) + ": 40 30 -UseTotalLength"
	(Indent-String $TestString 30 0) + ": 30 0"
	(Indent-String $TestString 30 0 -UseTotalLength) + ": 30 0 -UseTotalLength"
	}

	#--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==
	function Test-Cases () {
	#--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==
	$LongLine = '--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--=='
	$columnCount = '123456789 123456789 123456789 123456789 123456789 123456789'

	$LongLine
	Write-Host "InputString is empty """""
	$columnCount
	Test-It ""
	Write-Host

	$LongLine
	Write-Host "InputString is null"
	$columnCount
	Test-It $null
	Write-Host

	$LongLine
	Write-Host "InputString is a single space"
	$columnCount
	Test-It " "
	Write-Host

	$LongLine
	Write-Host "InputString is a single char (x)"
	$columnCount
	Test-It "X"
	Write-Host
	}

	<#
	.SYNOPSIS
	Just shows a couple of examples of using Indent-String.
	#>
	function Show-Examples () {
	#--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==--==
	Write-Host "Loop showing default behavior."
	$TabSize = 4
	$MaxLen = 0
	for ($i = 0; $i -le 9; $i++) {
	$Indent = $TabSize*$i
	(Indent-String "Level $i" $Indent $MaxLen) + ": $Indent $MaxLen"
	}
	Write-Host

	Write-Host "Same as above, except using ""-UseTotalLength"". Note that using ""0"" for TotalLength is not good."
	$TabSize = 4
	$MaxLen = 0
	for ($i = 0; $i -le 9; $i++) {
	$Indent = $TabSize*$i
	(Indent-String "Level $i" $Indent $MaxLen -UseTotalLength) + ": $Indent $MaxLen -UseTotalLength"
	}
	Write-Host

	Write-Host "Loop showing default behavior with a ""better"" value for ""TotalLength""."
	$TabSize = 4
	$MaxLen = 30
	for ($i = 0; $i -le 9; $i++) {
	$Indent = $TabSize*$i
	(Indent-String "Level $i" $Indent $MaxLen) + ": $Indent $MaxLen"
	}
	Write-Host

	Write-Host "Same as above, except specifying "" "" for LeftPadChar and ""."" for RightPadChar."
	$TabSize = 4
	$MaxLen = 30
	for ($i = 0; $i -le 9; $i++) {
	$Indent = $TabSize*$i
	(Indent-String "Level $i" $Indent $MaxLen " " ".") + ": $Indent $MaxLen "" "" ""."""
	}
	Write-Host

	Write-Host "Same as above, except using ""-UseTotalLength""."
	$TabSize = 4
	$MaxLen = 30
	for ($i = 0; $i -le 9; $i++) {
	$Indent = $TabSize*$i
	(Indent-String "Level $i" $Indent $MaxLen " " "." -UseTotalLength) + ": $Indent $MaxLen "" "" ""."" -UseTotalLength"
	}

	}