Out-String
Outputs input objects as a string.
Syntax
Out-String
[-Stream]
[-Width <Int32>]
[-InputObject <PSObject>]
[<CommonParameters>]Description
The Out-String cmdlet converts input objects into strings. By default, Out-String
accumulates the strings and returns them as a single string, but you can use the Stream
parameter to direct Out-String to return one line at a time or create an array of strings. This
cmdlet lets you search and manipulate string output as you would in traditional shells when object
manipulation is less convenient.
PowerShell also adds the OSS function that calls Out-String -Stream as a shorthand way to use
Out-String in a pipeline.
Examples
Example 1: Get the current culture and convert the data to strings
This example gets the regional settings for the current user and converts the object data to strings.
$C = Get-Culture | Select-Object -Property *
Out-String -InputObject $C -Width 100
Parent : en
LCID : 1033
KeyboardLayoutId : 1033
Name : en-US
IetfLanguageTag : en-US
DisplayName : English (United States)
NativeName : English (United States)
EnglishName : English (United States)
TwoLetterISOLanguageName : en
ThreeLetterISOLanguageName : eng
ThreeLetterWindowsLanguageName : ENU
CompareInfo : CompareInfo - en-US
TextInfo : TextInfo - en-US
IsNeutralCulture : False
CultureTypes : SpecificCultures, InstalledWin32Cultures, FrameworkCultures
NumberFormat : System.Globalization.NumberFormatInfo
DateTimeFormat : System.Globalization.DateTimeFormatInfo
Calendar : System.Globalization.GregorianCalendar
OptionalCalendars : {System.Globalization.GregorianCalendar,
System.Globalization.GregorianCalendar}
UseUserOverride : True
IsReadOnly : FalseThe $C variable stores a Selected.System.Globalization.CultureInfo object. The object is the
result of Get-Culture sending output down the pipeline to Select-Object. The Property
parameter uses an asterisk (*) wildcard to specify all properties are contained in the object.
Out-String uses the InputObject parameter to specify the CultureInfo object stored in the
$C variable. The objects in $C are converted to a string.
Note
To view the Out-String array, store the output to a variable and use an array index to view the
elements. For more information about the array index, see
about_Arrays.
$str = Out-String -InputObject $C -Width 100
Example 2: Working with objects
This example demonstrates the difference between working with objects and working with strings. The
command displays an alias that includes the text gcm, the alias for Get-Command.
Get-Alias | Out-String -Stream | Select-String -Pattern "gcm"
Alias gcm -> Get-CommandGet-Alias gets the System.Management.Automation.AliasInfo objects, one for each alias, and
sends the objects down the pipeline. Out-String uses the Stream parameter to convert each
object to a string rather than concatenating all the objects into a single string.
The System.String objects are sent down the pipeline and Select-String uses the Pattern
parameter to find matches for the text gcm.
Note
If you omit the Stream parameter, the command displays all the aliases because Select-String
finds the text gcm in the single string that Out-String returns.
Example 3: Use the Width parameter to prevent truncation.
While most output from Out-String is wrapped to the next line, there are scenarios where the
output is truncated by the formatting system before being passed to Out-String. You can avoid
truncation using the Width parameter.
PS> @{TestKey = ('x' * 200)} | Out-String
Name Value
---- -----
TestKey xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx...
PS> @{TestKey = ('x' * 200)} | Out-String -Width 250
Name Value
---- -----
TestKey xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxParameters
-InputObject
Specifies the objects to be written to a string. Enter a variable that contains the objects, or type a command or expression that gets the objects.
| Type: | PSObject |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Stream
By default, Out-String outputs a single string formatted as you would see it in the console
including any blank headers or trailing newlines. The Stream parameter enables Out-String to
output each line one by one. The only exception to this are multiline strings. In that case,
Out-String will still output the string as a single, multiline string.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Width
Specifies the number of characters in each line of output. Any additional characters are wrapped to the next line or truncated depending on the formatter cmdlet used. The Width parameter applies only to objects that are being formatted. If you omit this parameter, the width is determined by the characteristics of the host program. In terminal (console) windows, the current window width is used as the default value. PowerShell console windows default to a width of 80 characters on installation.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Inputs
You can pipe any object to this cmdlet.
Outputs
This cmdlet returns the string that it creates from the input object.
Notes
The cmdlets that contain the Out verb don't format objects. The Out cmdlets send objects to the
formatter for the specified display destination.
Related Links
PowerShell