Out-String

Syntax

Out-String
   [-NoNewLine]
   [-Width <Int32>]
   [-InputObject <PSObject>]
   [<CommonParameters>]

Out-String
   [-Stream]
   [-Width <Int32>]
   [-InputObject <PSObject>]
   [<CommonParameters>]

Description

The Out-String cmdlet converts the objects that Windows PowerShell manages into an array of 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 string at a time. This cmdlet lets you search and manipulate string output as you would in traditional shells when object manipulation is less convenient.

Examples

Example 1: Output text to the console as a string

PS C:\> Get-Content C:\test1\testfile2.txt | Out-String

This command sends the content of the Testfile2.txt file to the console as a single string. It uses the Get-Content cmdlet to get the content of the file. The pipeline operator (|) sends the content to Out-String , which sends the content to the console as a string.

Example 2: Get the current culture and convert the data to strings.

The first command uses the Get-Culture cmdlet to get the regional settings. The pipeline operator (|) sends the result to the Select-Object cmdlet, which selects all properties (*) of the culture object that **Get-Culture** returned. The command then stores the results in the $C variable.

PS C:\> $C = Get-Culture | Select-Object *



The second command uses the **Out-String** cmdlet to convert the **CultureInfo** object to a series of strings (one string for each property). It uses the *InputObject* parameter to pass the $C variable to **Out-String**. The *Width* parameter is set to 100 characters per line to prevent truncation.

PS C:\> Out-String -InputObject $C -Width 100

These commands get the regional settings for the current user and convert the data to strings.

Example 3: Working with objects

PS C:\> Get-Alias | Out-String -Stream | Select-String "Get-Command"

This example demonstrates the difference between working with objects and working with strings. The command displays aliases that include the phrase Get-Command. It uses the Get-Alias cmdlet to get a set of AliasInfo objects (one for each alias in the current session).

The pipeline operator (|) sends the output of the Get-Alias cmdlet to the Out-String cmdlet, which converts the objects to a series of strings. It uses the Stream parameter of Out-String to send each string individually, instead of concatenating them into a single string. Another pipeline operator sends the strings to the Select-String cmdlet, which selects the strings that include Get-Command anywhere in the string.

If you omit the Stream parameter, the command displays all of the aliases, because Select-String finds Get-Command in the single string that Out-String returns, and the formatter displays the string as a table.

Example 4: Using NoNewLine

PS C:\> "a", "b" | Out-String -NoNewLine

ab



PS C:\> @{key='value'} | Out-String

Name   Value

----   -----

key    value



PS C:\> @{key='value'} | Out-String -NoNewLine

Name Value  -----  key value

Not using -NoNewLine would have resulted in an output like a<newline>b<newline> . It should be noted that -NoNewLine does not strip newlines embedded within a string but strips out embedded newlines from formatter-generated output. Compare the second and third commands in this examples for clarity.

Optional Parameters

Inputs

System.Management.Automation.PSObject

You can pipe objects to Out-String .

Outputs

System.String

Out-String returns the string that it creates from the input object.

Notes

• The cmdlets that contain the Out verb that do not format objects; they just render them and send them to the specified display destination. If you send an unformatted object to an Out cmdlet, the cmdlet sends it to a formatting cmdlet before rendering it.
• The Out cmdlets do not have parameters that take names or file paths. To send data to an Out cmdlet, use a pipeline operator (|) to send the output of a Windows PowerShell command to the cmdlet. You can also store data in a variable and use the InputObject parameter to pass the data to the cmdlet.

*

Related Links

• Out-File
• Out-GridView
• Out-Printer