diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_For.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_For.md index d81f4512424..338e4b4f068 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_For.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_For.md @@ -1,7 +1,7 @@ --- description: Describes a language command you can use to run statements based on a conditional test. Locale: en-US -ms.date: 07/21/2021 +ms.date: 06/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_for?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about For @@ -119,7 +119,7 @@ for (($i = 0), ($j = 0); $i -lt 10 -and $j -lt 10; $i++,$j++) For more information, see [about_Logical_Operators](about_Logical_Operators.md). -### Examples +### Syntax examples At a minimum, a `For` statement requires the parenthesis surrounding the **Init**, **Condition**, and **Repeat** part of the statement and a command @@ -227,6 +227,182 @@ The `For` loop can also be written on one line as in the following example. for ($i = 0; $i -lt 10; $i++) { Write-Host $i } ``` +### Functional example + +The following example demonstrates how you can use a `For` loop to iterate over +an array of files and rename them. The files in the `work_items` folder have +their work item ID as the filename. The loop iterates through the files +to ensure that the ID number is zero-padded to five digits. + +First, the code retrieves the list of work item data files. They're all JSON +files that use the format `-` for their name. +With the file info objects saved to the `$fileList` variable, you can sort them +by name and see that while items are grouped by type, the ordering of the items +by ID is unexpected. + +```powershell +$fileList = Get-ChildItem -Path ./work_items +$fileList | Sort-Object -Descending -Property Name +``` + +```Output +bug-219.json +bug-41.json +bug-500.json +bug-697.json +bug-819.json +bug-840.json +feat-176.json +feat-367.json +feat-373.json +feat-434.json +feat-676.json +feat-690.json +feat-880.json +feat-944.json +maint-103.json +maint-367.json +maint-454.json +maint-49.json +maint-562.json +maint-579.json +``` + +To ensure that you can sort the work items alphanumerically, the work item +numbers need to be zero-padded. + +The code does this by first searching for the work item with the longest +numerical suffix. It loops over the files using a `for` loop, using the index +to access each file in the array. It compares each filename to a regular +expression pattern to extract the work item number as a string instead of an +integer. Then it compares the lengths of the work item numbers to find the +longest number. + +```powershell +# Default the longest numeral count to 1, since it can't be smaller. +$longestNumeralCount = 1 + +# Regular expression to find the numerals in the filename - use a template +# to simplify updating the pattern as needed. +$patternTemplate = '-(?{{{0},{1}}})\.json' +$pattern = $patternTemplate -f $longestNumeralCount + +# Iterate, checking the length of the work item number as a string. +for ( + $i = 0 # Start at zero for first array item. + $i -lt $fileList.Count # Stop on the last item in the array. + $i++ # Increment by one to step through the array. +) { + if ($fileList[$i].Name -match $pattern) { + $numeralCount = $Matches.WorkItemNumber.Length + if ($numeralCount -gt $longestNumeralCount) { + # Count is higher, check against it for remaining items. + $longestNumeralCount = $numeralCount + # Update the pattern to speed up the search, ignoring items + # with a smaller numeral count using pattern matching. + $pattern = $patternTemplate -f $longestNumeralCount + } + } +} +``` + +Now that you know the maximum numeral count for the work items, you can loop +over the files to rename them as needed. The next snippet of code iterates over +the file list again, padding them as needed. It uses another regular expression +pattern to only process files with a numeral count smaller than the maximum. + +```powershell +# Regular expression to find the numerals in the filename, but only if the +# numeral count is smaller than the longest numeral count. +$pattern = $patternTemplate -f 1, ($longestNumeralCount - 1) +for ( + $i = 0 # Start at zero for first array item. + $i -lt $fileList.Count # Stop on the last item in the array. + $i++ # Increment by one to step through the array. +) { + # Get the file from the array to process + $file = $fileList[$i] + + # If the file doesn't need to be renamed, continue to the next file + if ($file.Name -notmatch $pattern) { + continue + } + + # Get the work item number from the regular expression, create the + # padded string from it, and define the new filename by replacing + # the original number string with the padded number string. + $workItemNumber = $Matches.WorkItemNumber + $paddedNumber = "{0:d$longestNumeralCount}" -f $workItemNumber + $paddedName = $file.Name -replace $workItemNumber, $paddedNumber + + # Rename the file with the padded work item number. + $file | Rename-Item -NewName $paddedName +} +``` + +Now that the files are renamed, you can retrieve the list of files again and +sort both the old and new files by name. The following snippet retrieves a +the files again to save in a new array and compare with the initial set of +objects. Then it sorts both arrays of files, saving the sorted arrays into +the new variables `$sortedOriginal` and `$sortedPadded`. Finally, it uses a +`for` loop to iterate over the arrays and output an object with the following +properties: + +- **Index** represents the current index in the sorted arrays. +- **Original** is the item in the sorted array of original filenamess at the + current index. +- **Padded** is the item in the sorted array of padded filenames at the current + index. + +```powershell +$paddedList = Get-ChildItem -path ./work_items + +# Sort both file lists by name. +$sortedOriginal = $fileList | Sort-Object -Property Name +$sortedPadded = $renamedList | Sort-Object -Property Name + +# Iterate over the arrays and output an object to simplify comparing how +# the arrays were sorted before and after padding the work item numbers. +for ( + $i = 0 + $i -lt $fileList.Count + $i++ +) { + [pscustomobject] @{ + Index = $i + Original = $sortedOriginal[$i].Name + Padded = $sortedPadded[$i].Name + } +} +``` + +```Output +Index Original Padded +----- -------- ------ + 0 bug-219.json bug-00041.json + 1 bug-41.json bug-00219.json + 2 bug-500.json bug-00500.json + 3 bug-697.json bug-00697.json + 4 bug-819.json bug-00819.json + 5 bug-840.json bug-00840.json + 6 feat-176.json feat-00176.json + 7 feat-367.json feat-00367.json + 8 feat-373.json feat-00373.json + 9 feat-434.json feat-00434.json + 10 feat-676.json feat-00676.json + 11 feat-690.json feat-00690.json + 12 feat-880.json feat-00880.json + 13 feat-944.json feat-00944.json + 14 maint-103.json maint-00049.json + 15 maint-367.json maint-00103.json + 16 maint-454.json maint-00367.json + 17 maint-49.json maint-00454.json + 18 maint-562.json maint-00562.json + 19 maint-579.json maint-00579.json +``` + +In the output, the sorted work items after padding are in the expected order. + ## See also - [about_Comparison_Operators](about_Comparison_Operators.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Function_Provider.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Function_Provider.md index 1dbe78584b9..57314e593cc 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Function_Provider.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Function_Provider.md @@ -1,7 +1,7 @@ --- description: Function Locale: en-US -ms.date: 01/17/2023 +ms.date: 06/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_function_provider?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Function Provider @@ -162,10 +162,10 @@ in the `Function:` drive, you can omit the drive name. ## Deleting a function -This command deletes the `more:` function from the current session. +This command deletes the `more` function from the current session. ```powershell -Remove-Item Function:more: +Remove-Item Function:more ``` ## Changing a function diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions.md index 37837027301..9083ad55238 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions.md @@ -1,7 +1,7 @@ --- description: Describes how to create and use functions in PowerShell. Locale: en-US -ms.date: 05/17/2024 +ms.date: 06/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Functions @@ -25,6 +25,19 @@ Functions can be as simple as: function Get-PowerShellProcess { Get-Process PowerShell } ``` +Once a function is defined, you can use it like the built-in cmdlets. For +example, to call the newly defined `Get-PowerShellProcess` function: + +```powershell +Get-PowerShellProcess +``` + +```Output + NPM(K) PM(M) WS(M) CPU(s) Id SI ProcessName + ------ ----- ----- ------ -- -- ----------- + 110 78.72 172.39 10.62 10936 1 powershell +``` + A function can also be as complex as a cmdlet or an application. Like cmdlets, functions can have parameters. The parameters can be named, diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Set-Date.md b/reference/5.1/Microsoft.PowerShell.Utility/Set-Date.md index b6d7e6b0f1d..72f87aec04f 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Set-Date.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Set-Date.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 06/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/set-date?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Set-Date @@ -33,14 +33,17 @@ The `Set-Date` cmdlet changes the system date and time on the computer to a date specify. You can specify a new date and/or time by typing a string or by passing a **DateTime** or -**TimeSpan** object to `Set-Date`. To specify a new date or time, use the **Date** parameter. -To specify a change interval, use the **Adjust** parameter. +**TimeSpan** object to `Set-Date`. To specify a new date or time, use the **Date** parameter. To +specify a change interval, use the **Adjust** parameter. + +You must have administrative rights to change the system date and time. On Windows, start PowerShell +with the **Run as administrator** option. ## EXAMPLES ### Example 1: Add three days to the system date -This command adds three days to the current system date. It does not affect the time. The command +This command adds three days to the current system date. It doesn't affect the time. The command uses the **Date** parameter to specify the date. The `Get-Date` cmdlet returns the current date as a **DateTime** object. The **DateTime** object's @@ -57,8 +60,8 @@ This example sets the current system time back by 10 minutes. The **Adjust** parameter allows you to specify an interval of change (minus ten minutes) in the standard time format for the locale. -The **DisplayHint** parameter tells PowerShell to display only the time, but it does not -affect the **DateTime** object that `Set-Date` returns. +The **DisplayHint** parameter tells PowerShell to display only the time, but it doesn't affect the +**DateTime** object that `Set-Date` returns. ```powershell Set-Date -Adjust -0:10:0 -DisplayHint Time @@ -92,13 +95,27 @@ $90mins = New-TimeSpan -Minutes 90 Set-Date -Adjust $90mins ``` +### 5: Change to a specific date and time + +The following example sets the date and time to a specific value. + +```powershell +PS> Get-Date + +Monday, June 10, 2024 2:05:48 PM + +PS> Set-Date '6/11/2024 2:05:48 PM' + +Tuesday, June 11, 2024 2:05:48 PM +``` + ## PARAMETERS ### -Adjust -Specifies the value for which this cmdlet adds or subtracts from the current date and time. -can type an adjustment in standard date and time format for your locale or use the **Adjust** -parameter to pass a **TimeSpan** object from `New-TimeSpan` to `Set-Date`. +Specifies the value for which this cmdlet adds or subtracts from the current date and time. You can +type an adjustment in standard date and time format for your locale or use the **Adjust** parameter +to pass a **TimeSpan** object from `New-TimeSpan` to `Set-Date`. ```yaml Type: System.TimeSpan @@ -114,12 +131,12 @@ Accept wildcard characters: False ### -Date -Changes the date and time to the specified values. -You can type a new date in the short date format and a time in the standard time format for your -locale. Or, you can pass a **DateTime** object from `Get-Date`. +Changes the date and time to the specified values. You can type a new date in the short date format +and a time in the standard time format for your locale. Or, you can pass a **DateTime** object from +`Get-Date`. If you specify a date, but not a time, `Set-Date` changes the time to midnight on the specified -date. If you specify only a time, it does not change the date. +date. If you specify only a time, it doesn't change the date. ```yaml Type: System.DateTime @@ -135,15 +152,15 @@ Accept wildcard characters: False ### -DisplayHint -Specifies which elements of the date and time are displayed.The acceptable values for this parameter -are: +Specifies which elements of the date and time are displayed. The acceptable values for this +parameter are: - `Date` - displays only the date. - `Time` - displays only the time. - `DateTime` - displays the date and time. -This parameter affects only the display. -It does not affect the **DateTime** object that `Get-Date` retrieves. +This parameter affects only the display. It doesn't affect the **DateTime** object that `Get-Date` +retrieves. ```yaml Type: Microsoft.PowerShell.Commands.DisplayHintType @@ -176,8 +193,7 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. +Shows what would happen if the cmdlet runs. The cmdlet isn't run. ```yaml Type: System.Management.Automation.SwitchParameter @@ -195,7 +211,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS diff --git a/reference/5.1/Microsoft.PowerShell.Utility/Update-TypeData.md b/reference/5.1/Microsoft.PowerShell.Utility/Update-TypeData.md index 5ed7c0f173c..0663be4cd30 100644 --- a/reference/5.1/Microsoft.PowerShell.Utility/Update-TypeData.md +++ b/reference/5.1/Microsoft.PowerShell.Utility/Update-TypeData.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 06/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/update-typedata?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: Update-TypeData @@ -144,7 +144,7 @@ when no properties are specified. Because the type data is not specified in a `T is effective only in the current session. ```powershell -Update-TypeData -TypeName "System.DateTime" -DefaultDisplayPropertySet "DateTime, DayOfYear, Quarter" +Update-TypeData -TypeName "System.DateTime" -DefaultDisplayPropertySet "DateTime", "DayOfYear", "Quarter" Get-Date | Format-List ``` diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_For.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_For.md index 6cbaa9af021..f16be7069fe 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_For.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_For.md @@ -1,7 +1,7 @@ --- description: Describes a language command you can use to run statements based on a conditional test. Locale: en-US -ms.date: 07/21/2021 +ms.date: 06/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_for?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about For @@ -119,7 +119,7 @@ for (($i = 0), ($j = 0); $i -lt 10 -and $j -lt 10; $i++,$j++) For more information, see [about_Logical_Operators](about_Logical_Operators.md). -### Examples +### Syntax examples At a minimum, a `For` statement requires the parenthesis surrounding the **Init**, **Condition**, and **Repeat** part of the statement and a command @@ -227,6 +227,182 @@ The `For` loop can also be written on one line as in the following example. for ($i = 0; $i -lt 10; $i++) { Write-Host $i } ``` +### Functional example + +The following example demonstrates how you can use a `For` loop to iterate over +an array of files and rename them. The files in the `work_items` folder have +their work item ID as the filename. The loop iterates through the files +to ensure that the ID number is zero-padded to five digits. + +First, the code retrieves the list of work item data files. They're all JSON +files that use the format `-` for their name. +With the file info objects saved to the `$fileList` variable, you can sort them +by name and see that while items are grouped by type, the ordering of the items +by ID is unexpected. + +```powershell +$fileList = Get-ChildItem -Path ./work_items +$fileList | Sort-Object -Descending -Property Name +``` + +```Output +bug-219.json +bug-41.json +bug-500.json +bug-697.json +bug-819.json +bug-840.json +feat-176.json +feat-367.json +feat-373.json +feat-434.json +feat-676.json +feat-690.json +feat-880.json +feat-944.json +maint-103.json +maint-367.json +maint-454.json +maint-49.json +maint-562.json +maint-579.json +``` + +To ensure that you can sort the work items alphanumerically, the work item +numbers need to be zero-padded. + +The code does this by first searching for the work item with the longest +numerical suffix. It loops over the files using a `for` loop, using the index +to access each file in the array. It compares each filename to a regular +expression pattern to extract the work item number as a string instead of an +integer. Then it compares the lengths of the work item numbers to find the +longest number. + +```powershell +# Default the longest numeral count to 1, since it can't be smaller. +$longestNumeralCount = 1 + +# Regular expression to find the numerals in the filename - use a template +# to simplify updating the pattern as needed. +$patternTemplate = '-(?{{{0},{1}}})\.json' +$pattern = $patternTemplate -f $longestNumeralCount + +# Iterate, checking the length of the work item number as a string. +for ( + $i = 0 # Start at zero for first array item. + $i -lt $fileList.Count # Stop on the last item in the array. + $i++ # Increment by one to step through the array. +) { + if ($fileList[$i].Name -match $pattern) { + $numeralCount = $Matches.WorkItemNumber.Length + if ($numeralCount -gt $longestNumeralCount) { + # Count is higher, check against it for remaining items. + $longestNumeralCount = $numeralCount + # Update the pattern to speed up the search, ignoring items + # with a smaller numeral count using pattern matching. + $pattern = $patternTemplate -f $longestNumeralCount + } + } +} +``` + +Now that you know the maximum numeral count for the work items, you can loop +over the files to rename them as needed. The next snippet of code iterates over +the file list again, padding them as needed. It uses another regular expression +pattern to only process files with a numeral count smaller than the maximum. + +```powershell +# Regular expression to find the numerals in the filename, but only if the +# numeral count is smaller than the longest numeral count. +$pattern = $patternTemplate -f 1, ($longestNumeralCount - 1) +for ( + $i = 0 # Start at zero for first array item. + $i -lt $fileList.Count # Stop on the last item in the array. + $i++ # Increment by one to step through the array. +) { + # Get the file from the array to process + $file = $fileList[$i] + + # If the file doesn't need to be renamed, continue to the next file + if ($file.Name -notmatch $pattern) { + continue + } + + # Get the work item number from the regular expression, create the + # padded string from it, and define the new filename by replacing + # the original number string with the padded number string. + $workItemNumber = $Matches.WorkItemNumber + $paddedNumber = "{0:d$longestNumeralCount}" -f $workItemNumber + $paddedName = $file.Name -replace $workItemNumber, $paddedNumber + + # Rename the file with the padded work item number. + $file | Rename-Item -NewName $paddedName +} +``` + +Now that the files are renamed, you can retrieve the list of files again and +sort both the old and new files by name. The following snippet retrieves a +the files again to save in a new array and compare with the initial set of +objects. Then it sorts both arrays of files, saving the sorted arrays into +the new variables `$sortedOriginal` and `$sortedPadded`. Finally, it uses a +`for` loop to iterate over the arrays and output an object with the following +properties: + +- **Index** represents the current index in the sorted arrays. +- **Original** is the item in the sorted array of original filenamess at the + current index. +- **Padded** is the item in the sorted array of padded filenames at the current + index. + +```powershell +$paddedList = Get-ChildItem -path ./work_items + +# Sort both file lists by name. +$sortedOriginal = $fileList | Sort-Object -Property Name +$sortedPadded = $renamedList | Sort-Object -Property Name + +# Iterate over the arrays and output an object to simplify comparing how +# the arrays were sorted before and after padding the work item numbers. +for ( + $i = 0 + $i -lt $fileList.Count + $i++ +) { + [pscustomobject] @{ + Index = $i + Original = $sortedOriginal[$i].Name + Padded = $sortedPadded[$i].Name + } +} +``` + +```Output +Index Original Padded +----- -------- ------ + 0 bug-219.json bug-00041.json + 1 bug-41.json bug-00219.json + 2 bug-500.json bug-00500.json + 3 bug-697.json bug-00697.json + 4 bug-819.json bug-00819.json + 5 bug-840.json bug-00840.json + 6 feat-176.json feat-00176.json + 7 feat-367.json feat-00367.json + 8 feat-373.json feat-00373.json + 9 feat-434.json feat-00434.json + 10 feat-676.json feat-00676.json + 11 feat-690.json feat-00690.json + 12 feat-880.json feat-00880.json + 13 feat-944.json feat-00944.json + 14 maint-103.json maint-00049.json + 15 maint-367.json maint-00103.json + 16 maint-454.json maint-00367.json + 17 maint-49.json maint-00454.json + 18 maint-562.json maint-00562.json + 19 maint-579.json maint-00579.json +``` + +In the output, the sorted work items after padding are in the expected order. + ## See also - [about_Comparison_Operators](about_Comparison_Operators.md) diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Function_Provider.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Function_Provider.md index 664b5888618..e02cb78f064 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Function_Provider.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Function_Provider.md @@ -1,7 +1,7 @@ --- description: Function Locale: en-US -ms.date: 10/18/2018 +ms.date: 06/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_function_provider?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Function Provider @@ -161,10 +161,10 @@ in the `Function:` drive, you can omit the drive name. ## Deleting a function -This command deletes the `more:` function from the current session. +This command deletes the `more` function from the current session. ```powershell -Remove-Item Function:more: +Remove-Item Function:more ``` ## Changing a function diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Functions.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Functions.md index be0099caf2d..94895b982ec 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Functions.md @@ -1,7 +1,7 @@ --- description: Describes how to create and use functions in PowerShell. Locale: en-US -ms.date: 05/17/2024 +ms.date: 06/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Functions @@ -22,7 +22,20 @@ run as if you had typed them at the command prompt. Functions can be as simple as: ```powershell -function Get-PowerShellProcess { Get-Process PowerShell } +function Get-PowerShellProcess { Get-Process pwsh } +``` + +Once a function is defined, you can use it like the built-in cmdlets. For +example, to call the newly defined `Get-PowerShellProcess` function: + +```powershell +Get-PowerShellProcess +``` + +```Output + NPM(K) PM(M) WS(M) CPU(s) Id SI ProcessName + ------ ----- ----- ------ -- -- ----------- + 110 78.72 172.39 10.62 10936 1 pwsh ``` A function can also be as complex as a cmdlet or an application. diff --git a/reference/7.2/Microsoft.PowerShell.Utility/Set-Date.md b/reference/7.2/Microsoft.PowerShell.Utility/Set-Date.md index 64c176390d1..38eff1de859 100644 --- a/reference/7.2/Microsoft.PowerShell.Utility/Set-Date.md +++ b/reference/7.2/Microsoft.PowerShell.Utility/Set-Date.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 06/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/set-date?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: Set-Date @@ -33,14 +33,17 @@ The `Set-Date` cmdlet changes the system date and time on the computer to a date specify. You can specify a new date and/or time by typing a string or by passing a **DateTime** or -**TimeSpan** object to `Set-Date`. To specify a new date or time, use the **Date** parameter. -To specify a change interval, use the **Adjust** parameter. +**TimeSpan** object to `Set-Date`. To specify a new date or time, use the **Date** parameter. To +specify a change interval, use the **Adjust** parameter. + +You must have administrative rights to change the system date and time. On Windows, start PowerShell +with the **Run as administrator** option. ## EXAMPLES ### Example 1: Add three days to the system date -This command adds three days to the current system date. It does not affect the time. The command +This command adds three days to the current system date. It doesn't affect the time. The command uses the **Date** parameter to specify the date. The `Get-Date` cmdlet returns the current date as a **DateTime** object. The **DateTime** object's @@ -57,8 +60,8 @@ This example sets the current system time back by 10 minutes. The **Adjust** parameter allows you to specify an interval of change (minus ten minutes) in the standard time format for the locale. -The **DisplayHint** parameter tells PowerShell to display only the time, but it does not -affect the **DateTime** object that `Set-Date` returns. +The **DisplayHint** parameter tells PowerShell to display only the time, but it doesn't affect the +**DateTime** object that `Set-Date` returns. ```powershell Set-Date -Adjust -0:10:0 -DisplayHint Time @@ -92,13 +95,27 @@ $90mins = New-TimeSpan -Minutes 90 Set-Date -Adjust $90mins ``` +### 5: Change to a specific date and time + +The following example sets the date and time to a specific value. + +```powershell +PS> Get-Date + +Monday, June 10, 2024 2:05:48 PM + +PS> Set-Date '6/11/2024 2:05:48 PM' + +Tuesday, June 11, 2024 2:05:48 PM +``` + ## PARAMETERS ### -Adjust -Specifies the value for which this cmdlet adds or subtracts from the current date and time. -can type an adjustment in standard date and time format for your locale or use the **Adjust** -parameter to pass a **TimeSpan** object from `New-TimeSpan` to `Set-Date`. +Specifies the value for which this cmdlet adds or subtracts from the current date and time. You can +type an adjustment in standard date and time format for your locale or use the **Adjust** parameter +to pass a **TimeSpan** object from `New-TimeSpan` to `Set-Date`. ```yaml Type: System.TimeSpan @@ -114,12 +131,12 @@ Accept wildcard characters: False ### -Date -Changes the date and time to the specified values. -You can type a new date in the short date format and a time in the standard time format for your -locale. Or, you can pass a **DateTime** object from `Get-Date`. +Changes the date and time to the specified values. You can type a new date in the short date format +and a time in the standard time format for your locale. Or, you can pass a **DateTime** object from +`Get-Date`. If you specify a date, but not a time, `Set-Date` changes the time to midnight on the specified -date. If you specify only a time, it does not change the date. +date. If you specify only a time, it doesn't change the date. ```yaml Type: System.DateTime @@ -135,15 +152,15 @@ Accept wildcard characters: False ### -DisplayHint -Specifies which elements of the date and time are displayed.The acceptable values for this parameter -are: +Specifies which elements of the date and time are displayed. The acceptable values for this +parameter are: - `Date` - displays only the date. - `Time` - displays only the time. - `DateTime` - displays the date and time. -This parameter affects only the display. -It does not affect the **DateTime** object that `Get-Date` retrieves. +This parameter affects only the display. It doesn't affect the **DateTime** object that `Get-Date` +retrieves. ```yaml Type: Microsoft.PowerShell.Commands.DisplayHintType @@ -176,8 +193,7 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. +Shows what would happen if the cmdlet runs. The cmdlet isn't run. ```yaml Type: System.Management.Automation.SwitchParameter @@ -195,7 +211,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS diff --git a/reference/7.2/Microsoft.PowerShell.Utility/Update-TypeData.md b/reference/7.2/Microsoft.PowerShell.Utility/Update-TypeData.md index d0a731a4c81..2c1e591173c 100644 --- a/reference/7.2/Microsoft.PowerShell.Utility/Update-TypeData.md +++ b/reference/7.2/Microsoft.PowerShell.Utility/Update-TypeData.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 06/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/update-typedata?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: Update-TypeData @@ -144,7 +144,7 @@ when no properties are specified. Because the type data is not specified in a `T is effective only in the current session. ```powershell -Update-TypeData -TypeName "System.DateTime" -DefaultDisplayPropertySet "DateTime, DayOfYear, Quarter" +Update-TypeData -TypeName "System.DateTime" -DefaultDisplayPropertySet "DateTime", "DayOfYear", "Quarter" Get-Date | Format-List ``` diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_For.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_For.md index ba03469995a..202edded3bf 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_For.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_For.md @@ -1,7 +1,7 @@ --- description: Describes a language command you can use to run statements based on a conditional test. Locale: en-US -ms.date: 07/21/2021 +ms.date: 06/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_for?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about For @@ -119,7 +119,7 @@ for (($i = 0), ($j = 0); $i -lt 10 -and $j -lt 10; $i++,$j++) For more information, see [about_Logical_Operators](about_Logical_Operators.md). -### Examples +### Syntax examples At a minimum, a `For` statement requires the parenthesis surrounding the **Init**, **Condition**, and **Repeat** part of the statement and a command @@ -227,6 +227,182 @@ The `For` loop can also be written on one line as in the following example. for ($i = 0; $i -lt 10; $i++) { Write-Host $i } ``` +### Functional example + +The following example demonstrates how you can use a `For` loop to iterate over +an array of files and rename them. The files in the `work_items` folder have +their work item ID as the filename. The loop iterates through the files +to ensure that the ID number is zero-padded to five digits. + +First, the code retrieves the list of work item data files. They're all JSON +files that use the format `-` for their name. +With the file info objects saved to the `$fileList` variable, you can sort them +by name and see that while items are grouped by type, the ordering of the items +by ID is unexpected. + +```powershell +$fileList = Get-ChildItem -Path ./work_items +$fileList | Sort-Object -Descending -Property Name +``` + +```Output +bug-219.json +bug-41.json +bug-500.json +bug-697.json +bug-819.json +bug-840.json +feat-176.json +feat-367.json +feat-373.json +feat-434.json +feat-676.json +feat-690.json +feat-880.json +feat-944.json +maint-103.json +maint-367.json +maint-454.json +maint-49.json +maint-562.json +maint-579.json +``` + +To ensure that you can sort the work items alphanumerically, the work item +numbers need to be zero-padded. + +The code does this by first searching for the work item with the longest +numerical suffix. It loops over the files using a `for` loop, using the index +to access each file in the array. It compares each filename to a regular +expression pattern to extract the work item number as a string instead of an +integer. Then it compares the lengths of the work item numbers to find the +longest number. + +```powershell +# Default the longest numeral count to 1, since it can't be smaller. +$longestNumeralCount = 1 + +# Regular expression to find the numerals in the filename - use a template +# to simplify updating the pattern as needed. +$patternTemplate = '-(?{{{0},{1}}})\.json' +$pattern = $patternTemplate -f $longestNumeralCount + +# Iterate, checking the length of the work item number as a string. +for ( + $i = 0 # Start at zero for first array item. + $i -lt $fileList.Count # Stop on the last item in the array. + $i++ # Increment by one to step through the array. +) { + if ($fileList[$i].Name -match $pattern) { + $numeralCount = $Matches.WorkItemNumber.Length + if ($numeralCount -gt $longestNumeralCount) { + # Count is higher, check against it for remaining items. + $longestNumeralCount = $numeralCount + # Update the pattern to speed up the search, ignoring items + # with a smaller numeral count using pattern matching. + $pattern = $patternTemplate -f $longestNumeralCount + } + } +} +``` + +Now that you know the maximum numeral count for the work items, you can loop +over the files to rename them as needed. The next snippet of code iterates over +the file list again, padding them as needed. It uses another regular expression +pattern to only process files with a numeral count smaller than the maximum. + +```powershell +# Regular expression to find the numerals in the filename, but only if the +# numeral count is smaller than the longest numeral count. +$pattern = $patternTemplate -f 1, ($longestNumeralCount - 1) +for ( + $i = 0 # Start at zero for first array item. + $i -lt $fileList.Count # Stop on the last item in the array. + $i++ # Increment by one to step through the array. +) { + # Get the file from the array to process + $file = $fileList[$i] + + # If the file doesn't need to be renamed, continue to the next file + if ($file.Name -notmatch $pattern) { + continue + } + + # Get the work item number from the regular expression, create the + # padded string from it, and define the new filename by replacing + # the original number string with the padded number string. + $workItemNumber = $Matches.WorkItemNumber + $paddedNumber = "{0:d$longestNumeralCount}" -f $workItemNumber + $paddedName = $file.Name -replace $workItemNumber, $paddedNumber + + # Rename the file with the padded work item number. + $file | Rename-Item -NewName $paddedName +} +``` + +Now that the files are renamed, you can retrieve the list of files again and +sort both the old and new files by name. The following snippet retrieves a +the files again to save in a new array and compare with the initial set of +objects. Then it sorts both arrays of files, saving the sorted arrays into +the new variables `$sortedOriginal` and `$sortedPadded`. Finally, it uses a +`for` loop to iterate over the arrays and output an object with the following +properties: + +- **Index** represents the current index in the sorted arrays. +- **Original** is the item in the sorted array of original filenamess at the + current index. +- **Padded** is the item in the sorted array of padded filenames at the current + index. + +```powershell +$paddedList = Get-ChildItem -path ./work_items + +# Sort both file lists by name. +$sortedOriginal = $fileList | Sort-Object -Property Name +$sortedPadded = $renamedList | Sort-Object -Property Name + +# Iterate over the arrays and output an object to simplify comparing how +# the arrays were sorted before and after padding the work item numbers. +for ( + $i = 0 + $i -lt $fileList.Count + $i++ +) { + [pscustomobject] @{ + Index = $i + Original = $sortedOriginal[$i].Name + Padded = $sortedPadded[$i].Name + } +} +``` + +```Output +Index Original Padded +----- -------- ------ + 0 bug-219.json bug-00041.json + 1 bug-41.json bug-00219.json + 2 bug-500.json bug-00500.json + 3 bug-697.json bug-00697.json + 4 bug-819.json bug-00819.json + 5 bug-840.json bug-00840.json + 6 feat-176.json feat-00176.json + 7 feat-367.json feat-00367.json + 8 feat-373.json feat-00373.json + 9 feat-434.json feat-00434.json + 10 feat-676.json feat-00676.json + 11 feat-690.json feat-00690.json + 12 feat-880.json feat-00880.json + 13 feat-944.json feat-00944.json + 14 maint-103.json maint-00049.json + 15 maint-367.json maint-00103.json + 16 maint-454.json maint-00367.json + 17 maint-49.json maint-00454.json + 18 maint-562.json maint-00562.json + 19 maint-579.json maint-00579.json +``` + +In the output, the sorted work items after padding are in the expected order. + ## See also - [about_Comparison_Operators](about_Comparison_Operators.md) diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Function_Provider.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Function_Provider.md index 90bc5078433..146913f62e2 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Function_Provider.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Function_Provider.md @@ -1,7 +1,7 @@ --- description: Function Locale: en-US -ms.date: 01/17/2023 +ms.date: 06/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_function_provider?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Function Provider @@ -161,10 +161,10 @@ in the `Function:` drive, you can omit the drive name. ## Deleting a function -This command deletes the `more:` function from the current session. +This command deletes the `more` function from the current session. ```powershell -Remove-Item Function:more: +Remove-Item Function:more ``` ## Changing a function diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions.md index 9033377b013..987055093a6 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/7.4/Microsoft.PowerShell.Core/About/about_Functions.md @@ -1,7 +1,7 @@ --- description: Describes how to create and use functions in PowerShell. Locale: en-US -ms.date: 05/20/2024 +ms.date: 06/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Functions @@ -22,7 +22,20 @@ run as if you had typed them at the command prompt. Functions can be as simple as: ```powershell -function Get-PowerShellProcess { Get-Process PowerShell } +function Get-PowerShellProcess { Get-Process pwsh } +``` + +Once a function is defined, you can use it like the built-in cmdlets. For +example, to call the newly defined `Get-PowerShellProcess` function: + +```powershell +Get-PowerShellProcess +``` + +```Output + NPM(K) PM(M) WS(M) CPU(s) Id SI ProcessName + ------ ----- ----- ------ -- -- ----------- + 110 78.72 172.39 10.62 10936 1 pwsh ``` A function can also be as complex as a cmdlet or an application. diff --git a/reference/7.4/Microsoft.PowerShell.Utility/Set-Date.md b/reference/7.4/Microsoft.PowerShell.Utility/Set-Date.md index bbb0244610c..9a54ffdceca 100644 --- a/reference/7.4/Microsoft.PowerShell.Utility/Set-Date.md +++ b/reference/7.4/Microsoft.PowerShell.Utility/Set-Date.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 06/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/set-date?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: Set-Date @@ -33,14 +33,17 @@ The `Set-Date` cmdlet changes the system date and time on the computer to a date specify. You can specify a new date and/or time by typing a string or by passing a **DateTime** or -**TimeSpan** object to `Set-Date`. To specify a new date or time, use the **Date** parameter. -To specify a change interval, use the **Adjust** parameter. +**TimeSpan** object to `Set-Date`. To specify a new date or time, use the **Date** parameter. To +specify a change interval, use the **Adjust** parameter. + +You must have administrative rights to change the system date and time. On Windows, start PowerShell +with the **Run as administrator** option. ## EXAMPLES ### Example 1: Add three days to the system date -This command adds three days to the current system date. It does not affect the time. The command +This command adds three days to the current system date. It doesn't affect the time. The command uses the **Date** parameter to specify the date. The `Get-Date` cmdlet returns the current date as a **DateTime** object. The **DateTime** object's @@ -57,8 +60,8 @@ This example sets the current system time back by 10 minutes. The **Adjust** parameter allows you to specify an interval of change (minus ten minutes) in the standard time format for the locale. -The **DisplayHint** parameter tells PowerShell to display only the time, but it does not -affect the **DateTime** object that `Set-Date` returns. +The **DisplayHint** parameter tells PowerShell to display only the time, but it doesn't affect the +**DateTime** object that `Set-Date` returns. ```powershell Set-Date -Adjust -0:10:0 -DisplayHint Time @@ -92,13 +95,27 @@ $90mins = New-TimeSpan -Minutes 90 Set-Date -Adjust $90mins ``` +### 5: Change to a specific date and time + +The following example sets the date and time to a specific value. + +```powershell +PS> Get-Date + +Monday, June 10, 2024 2:05:48 PM + +PS> Set-Date '6/11/2024 2:05:48 PM' + +Tuesday, June 11, 2024 2:05:48 PM +``` + ## PARAMETERS ### -Adjust -Specifies the value for which this cmdlet adds or subtracts from the current date and time. -can type an adjustment in standard date and time format for your locale or use the **Adjust** -parameter to pass a **TimeSpan** object from `New-TimeSpan` to `Set-Date`. +Specifies the value for which this cmdlet adds or subtracts from the current date and time. You can +type an adjustment in standard date and time format for your locale or use the **Adjust** parameter +to pass a **TimeSpan** object from `New-TimeSpan` to `Set-Date`. ```yaml Type: System.TimeSpan @@ -114,12 +131,12 @@ Accept wildcard characters: False ### -Date -Changes the date and time to the specified values. -You can type a new date in the short date format and a time in the standard time format for your -locale. Or, you can pass a **DateTime** object from `Get-Date`. +Changes the date and time to the specified values. You can type a new date in the short date format +and a time in the standard time format for your locale. Or, you can pass a **DateTime** object from +`Get-Date`. If you specify a date, but not a time, `Set-Date` changes the time to midnight on the specified -date. If you specify only a time, it does not change the date. +date. If you specify only a time, it doesn't change the date. ```yaml Type: System.DateTime @@ -135,15 +152,15 @@ Accept wildcard characters: False ### -DisplayHint -Specifies which elements of the date and time are displayed.The acceptable values for this parameter -are: +Specifies which elements of the date and time are displayed. The acceptable values for this +parameter are: - `Date` - displays only the date. - `Time` - displays only the time. - `DateTime` - displays the date and time. -This parameter affects only the display. -It does not affect the **DateTime** object that `Get-Date` retrieves. +This parameter affects only the display. It doesn't affect the **DateTime** object that `Get-Date` +retrieves. ```yaml Type: Microsoft.PowerShell.Commands.DisplayHintType @@ -176,8 +193,7 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. +Shows what would happen if the cmdlet runs. The cmdlet isn't run. ```yaml Type: System.Management.Automation.SwitchParameter @@ -195,7 +211,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS diff --git a/reference/7.4/Microsoft.PowerShell.Utility/Update-TypeData.md b/reference/7.4/Microsoft.PowerShell.Utility/Update-TypeData.md index d7522077422..61fe4b60370 100644 --- a/reference/7.4/Microsoft.PowerShell.Utility/Update-TypeData.md +++ b/reference/7.4/Microsoft.PowerShell.Utility/Update-TypeData.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 06/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/update-typedata?view=powershell-7.4&WT.mc_id=ps-gethelp schema: 2.0.0 title: Update-TypeData @@ -144,7 +144,7 @@ when no properties are specified. Because the type data is not specified in a `T is effective only in the current session. ```powershell -Update-TypeData -TypeName "System.DateTime" -DefaultDisplayPropertySet "DateTime, DayOfYear, Quarter" +Update-TypeData -TypeName "System.DateTime" -DefaultDisplayPropertySet "DateTime", "DayOfYear", "Quarter" Get-Date | Format-List ``` diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_For.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_For.md index 87568fb6519..d12e26d1bbc 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_For.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_For.md @@ -1,7 +1,7 @@ --- description: Describes a language command you can use to run statements based on a conditional test. Locale: en-US -ms.date: 07/21/2021 +ms.date: 06/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_for?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about For @@ -119,7 +119,7 @@ for (($i = 0), ($j = 0); $i -lt 10 -and $j -lt 10; $i++,$j++) For more information, see [about_Logical_Operators](about_Logical_Operators.md). -### Examples +### Syntax examples At a minimum, a `For` statement requires the parenthesis surrounding the **Init**, **Condition**, and **Repeat** part of the statement and a command @@ -227,6 +227,182 @@ The `For` loop can also be written on one line as in the following example. for ($i = 0; $i -lt 10; $i++) { Write-Host $i } ``` +### Functional example + +The following example demonstrates how you can use a `For` loop to iterate over +an array of files and rename them. The files in the `work_items` folder have +their work item ID as the filename. The loop iterates through the files +to ensure that the ID number is zero-padded to five digits. + +First, the code retrieves the list of work item data files. They're all JSON +files that use the format `-` for their name. +With the file info objects saved to the `$fileList` variable, you can sort them +by name and see that while items are grouped by type, the ordering of the items +by ID is unexpected. + +```powershell +$fileList = Get-ChildItem -Path ./work_items +$fileList | Sort-Object -Descending -Property Name +``` + +```Output +bug-219.json +bug-41.json +bug-500.json +bug-697.json +bug-819.json +bug-840.json +feat-176.json +feat-367.json +feat-373.json +feat-434.json +feat-676.json +feat-690.json +feat-880.json +feat-944.json +maint-103.json +maint-367.json +maint-454.json +maint-49.json +maint-562.json +maint-579.json +``` + +To ensure that you can sort the work items alphanumerically, the work item +numbers need to be zero-padded. + +The code does this by first searching for the work item with the longest +numerical suffix. It loops over the files using a `for` loop, using the index +to access each file in the array. It compares each filename to a regular +expression pattern to extract the work item number as a string instead of an +integer. Then it compares the lengths of the work item numbers to find the +longest number. + +```powershell +# Default the longest numeral count to 1, since it can't be smaller. +$longestNumeralCount = 1 + +# Regular expression to find the numerals in the filename - use a template +# to simplify updating the pattern as needed. +$patternTemplate = '-(?{{{0},{1}}})\.json' +$pattern = $patternTemplate -f $longestNumeralCount + +# Iterate, checking the length of the work item number as a string. +for ( + $i = 0 # Start at zero for first array item. + $i -lt $fileList.Count # Stop on the last item in the array. + $i++ # Increment by one to step through the array. +) { + if ($fileList[$i].Name -match $pattern) { + $numeralCount = $Matches.WorkItemNumber.Length + if ($numeralCount -gt $longestNumeralCount) { + # Count is higher, check against it for remaining items. + $longestNumeralCount = $numeralCount + # Update the pattern to speed up the search, ignoring items + # with a smaller numeral count using pattern matching. + $pattern = $patternTemplate -f $longestNumeralCount + } + } +} +``` + +Now that you know the maximum numeral count for the work items, you can loop +over the files to rename them as needed. The next snippet of code iterates over +the file list again, padding them as needed. It uses another regular expression +pattern to only process files with a numeral count smaller than the maximum. + +```powershell +# Regular expression to find the numerals in the filename, but only if the +# numeral count is smaller than the longest numeral count. +$pattern = $patternTemplate -f 1, ($longestNumeralCount - 1) +for ( + $i = 0 # Start at zero for first array item. + $i -lt $fileList.Count # Stop on the last item in the array. + $i++ # Increment by one to step through the array. +) { + # Get the file from the array to process + $file = $fileList[$i] + + # If the file doesn't need to be renamed, continue to the next file + if ($file.Name -notmatch $pattern) { + continue + } + + # Get the work item number from the regular expression, create the + # padded string from it, and define the new filename by replacing + # the original number string with the padded number string. + $workItemNumber = $Matches.WorkItemNumber + $paddedNumber = "{0:d$longestNumeralCount}" -f $workItemNumber + $paddedName = $file.Name -replace $workItemNumber, $paddedNumber + + # Rename the file with the padded work item number. + $file | Rename-Item -NewName $paddedName +} +``` + +Now that the files are renamed, you can retrieve the list of files again and +sort both the old and new files by name. The following snippet retrieves a +the files again to save in a new array and compare with the initial set of +objects. Then it sorts both arrays of files, saving the sorted arrays into +the new variables `$sortedOriginal` and `$sortedPadded`. Finally, it uses a +`for` loop to iterate over the arrays and output an object with the following +properties: + +- **Index** represents the current index in the sorted arrays. +- **Original** is the item in the sorted array of original filenamess at the + current index. +- **Padded** is the item in the sorted array of padded filenames at the current + index. + +```powershell +$paddedList = Get-ChildItem -path ./work_items + +# Sort both file lists by name. +$sortedOriginal = $fileList | Sort-Object -Property Name +$sortedPadded = $renamedList | Sort-Object -Property Name + +# Iterate over the arrays and output an object to simplify comparing how +# the arrays were sorted before and after padding the work item numbers. +for ( + $i = 0 + $i -lt $fileList.Count + $i++ +) { + [pscustomobject] @{ + Index = $i + Original = $sortedOriginal[$i].Name + Padded = $sortedPadded[$i].Name + } +} +``` + +```Output +Index Original Padded +----- -------- ------ + 0 bug-219.json bug-00041.json + 1 bug-41.json bug-00219.json + 2 bug-500.json bug-00500.json + 3 bug-697.json bug-00697.json + 4 bug-819.json bug-00819.json + 5 bug-840.json bug-00840.json + 6 feat-176.json feat-00176.json + 7 feat-367.json feat-00367.json + 8 feat-373.json feat-00373.json + 9 feat-434.json feat-00434.json + 10 feat-676.json feat-00676.json + 11 feat-690.json feat-00690.json + 12 feat-880.json feat-00880.json + 13 feat-944.json feat-00944.json + 14 maint-103.json maint-00049.json + 15 maint-367.json maint-00103.json + 16 maint-454.json maint-00367.json + 17 maint-49.json maint-00454.json + 18 maint-562.json maint-00562.json + 19 maint-579.json maint-00579.json +``` + +In the output, the sorted work items after padding are in the expected order. + ## See also - [about_Comparison_Operators](about_Comparison_Operators.md) diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Function_Provider.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Function_Provider.md index 9fd2fe33054..011e05592ea 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Function_Provider.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Function_Provider.md @@ -1,7 +1,7 @@ --- description: Function Locale: en-US -ms.date: 01/17/2023 +ms.date: 06/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_function_provider?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Function Provider @@ -161,10 +161,10 @@ in the `Function:` drive, you can omit the drive name. ## Deleting a function -This command deletes the `more:` function from the current session. +This command deletes the `more` function from the current session. ```powershell -Remove-Item Function:more: +Remove-Item Function:more ``` ## Changing a function diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions.md index 676ff171547..256ee385278 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions.md +++ b/reference/7.5/Microsoft.PowerShell.Core/About/about_Functions.md @@ -1,7 +1,7 @@ --- description: Describes how to create and use functions in PowerShell. Locale: en-US -ms.date: 05/20/2024 +ms.date: 06/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Functions @@ -22,7 +22,20 @@ run as if you had typed them at the command prompt. Functions can be as simple as: ```powershell -function Get-PowerShellProcess { Get-Process PowerShell } +function Get-PowerShellProcess { Get-Process pwsh } +``` + +Once a function is defined, you can use it like the built-in cmdlets. For +example, to call the newly defined `Get-PowerShellProcess` function: + +```powershell +Get-PowerShellProcess +``` + +```Output + NPM(K) PM(M) WS(M) CPU(s) Id SI ProcessName + ------ ----- ----- ------ -- -- ----------- + 110 78.72 172.39 10.62 10936 1 pwsh ``` A function can also be as complex as a cmdlet or an application. diff --git a/reference/7.5/Microsoft.PowerShell.Utility/Set-Date.md b/reference/7.5/Microsoft.PowerShell.Utility/Set-Date.md index ad8bf1ac601..71a6d95cf7b 100644 --- a/reference/7.5/Microsoft.PowerShell.Utility/Set-Date.md +++ b/reference/7.5/Microsoft.PowerShell.Utility/Set-Date.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 06/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/set-date?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: Set-Date @@ -33,14 +33,17 @@ The `Set-Date` cmdlet changes the system date and time on the computer to a date specify. You can specify a new date and/or time by typing a string or by passing a **DateTime** or -**TimeSpan** object to `Set-Date`. To specify a new date or time, use the **Date** parameter. -To specify a change interval, use the **Adjust** parameter. +**TimeSpan** object to `Set-Date`. To specify a new date or time, use the **Date** parameter. To +specify a change interval, use the **Adjust** parameter. + +You must have administrative rights to change the system date and time. On Windows, start PowerShell +with the **Run as administrator** option. ## EXAMPLES ### Example 1: Add three days to the system date -This command adds three days to the current system date. It does not affect the time. The command +This command adds three days to the current system date. It doesn't affect the time. The command uses the **Date** parameter to specify the date. The `Get-Date` cmdlet returns the current date as a **DateTime** object. The **DateTime** object's @@ -57,8 +60,8 @@ This example sets the current system time back by 10 minutes. The **Adjust** parameter allows you to specify an interval of change (minus ten minutes) in the standard time format for the locale. -The **DisplayHint** parameter tells PowerShell to display only the time, but it does not -affect the **DateTime** object that `Set-Date` returns. +The **DisplayHint** parameter tells PowerShell to display only the time, but it doesn't affect the +**DateTime** object that `Set-Date` returns. ```powershell Set-Date -Adjust -0:10:0 -DisplayHint Time @@ -92,13 +95,27 @@ $90mins = New-TimeSpan -Minutes 90 Set-Date -Adjust $90mins ``` +### 5: Change to a specific date and time + +The following example sets the date and time to a specific value. + +```powershell +PS> Get-Date + +Monday, June 10, 2024 2:05:48 PM + +PS> Set-Date '6/11/2024 2:05:48 PM' + +Tuesday, June 11, 2024 2:05:48 PM +``` + ## PARAMETERS ### -Adjust -Specifies the value for which this cmdlet adds or subtracts from the current date and time. -can type an adjustment in standard date and time format for your locale or use the **Adjust** -parameter to pass a **TimeSpan** object from `New-TimeSpan` to `Set-Date`. +Specifies the value for which this cmdlet adds or subtracts from the current date and time. You can +type an adjustment in standard date and time format for your locale or use the **Adjust** parameter +to pass a **TimeSpan** object from `New-TimeSpan` to `Set-Date`. ```yaml Type: System.TimeSpan @@ -114,12 +131,12 @@ Accept wildcard characters: False ### -Date -Changes the date and time to the specified values. -You can type a new date in the short date format and a time in the standard time format for your -locale. Or, you can pass a **DateTime** object from `Get-Date`. +Changes the date and time to the specified values. You can type a new date in the short date format +and a time in the standard time format for your locale. Or, you can pass a **DateTime** object from +`Get-Date`. If you specify a date, but not a time, `Set-Date` changes the time to midnight on the specified -date. If you specify only a time, it does not change the date. +date. If you specify only a time, it doesn't change the date. ```yaml Type: System.DateTime @@ -135,15 +152,15 @@ Accept wildcard characters: False ### -DisplayHint -Specifies which elements of the date and time are displayed.The acceptable values for this parameter -are: +Specifies which elements of the date and time are displayed. The acceptable values for this +parameter are: - `Date` - displays only the date. - `Time` - displays only the time. - `DateTime` - displays the date and time. -This parameter affects only the display. -It does not affect the **DateTime** object that `Get-Date` retrieves. +This parameter affects only the display. It doesn't affect the **DateTime** object that `Get-Date` +retrieves. ```yaml Type: Microsoft.PowerShell.Commands.DisplayHintType @@ -176,8 +193,7 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. +Shows what would happen if the cmdlet runs. The cmdlet isn't run. ```yaml Type: System.Management.Automation.SwitchParameter @@ -195,7 +211,8 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, --WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](../Microsoft.PowerShell.Core/About/about_CommonParameters.md). ## INPUTS diff --git a/reference/7.5/Microsoft.PowerShell.Utility/Update-TypeData.md b/reference/7.5/Microsoft.PowerShell.Utility/Update-TypeData.md index 37f89fbb9f5..d9183f48057 100644 --- a/reference/7.5/Microsoft.PowerShell.Utility/Update-TypeData.md +++ b/reference/7.5/Microsoft.PowerShell.Utility/Update-TypeData.md @@ -2,7 +2,7 @@ external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml Locale: en-US Module Name: Microsoft.PowerShell.Utility -ms.date: 12/12/2022 +ms.date: 06/10/2024 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/update-typedata?view=powershell-7.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: Update-TypeData @@ -144,7 +144,7 @@ when no properties are specified. Because the type data is not specified in a `T is effective only in the current session. ```powershell -Update-TypeData -TypeName "System.DateTime" -DefaultDisplayPropertySet "DateTime, DayOfYear, Quarter" +Update-TypeData -TypeName "System.DateTime" -DefaultDisplayPropertySet "DateTime", "DayOfYear", "Quarter" Get-Date | Format-List ``` diff --git a/reference/docs-conceptual/learn/shell/using-aliases.md b/reference/docs-conceptual/learn/shell/using-aliases.md index 6954a3464e5..7da67ef63d0 100644 --- a/reference/docs-conceptual/learn/shell/using-aliases.md +++ b/reference/docs-conceptual/learn/shell/using-aliases.md @@ -1,6 +1,6 @@ --- description: This article describe how to use aliases in PowerShell. -ms.date: 11/16/2022 +ms.date: 06/10/2024 title: Using aliases --- # Using aliases @@ -11,7 +11,8 @@ executable name. ## Managing command aliases -PowerShell provides cmdlets for managing command aliases. +PowerShell provides cmdlets for managing command aliases. The following command shows the cmdlets +that manage aliases. ```powershell Get-Command -Noun Alias @@ -57,6 +58,14 @@ CommandType Name Alias gci -> Get-ChildItem ``` +To create an alias, use the `Set-Alias` command. You can create aliases for cmdlets, functions, +scripts, and native executables files. + +```powershell +Set-Alias -Name np -Value Notepad.exe +Set-Alias -Name cmpo -Value Compare-Object +``` + ## Compatibility aliases in Windows PowerShell has several aliases that allow **UNIX** and **cmd.exe** users to use familiar commands in