Skip to content

ConvertTo-ZLibString.md

Latest commit

 

History

History
210 lines (143 loc) · 5.89 KB

ConvertTo-ZLibString.md

File metadata and controls

210 lines (143 loc) · 5.89 KB
external help file PSCompression.dll-Help.xml
Module Name PSCompression
online version https://github.com/santisq/PSCompression
schema 2.0.0

ConvertTo-ZLibString

SYNOPSIS

Compresses input strings into a ZLib-compressed Base64-encoded string.

SYNTAX

ConvertTo-ZLibString
    [-InputObject] <String[]>
    [-Encoding <Encoding>]
    [-CompressionLevel <CompressionLevel>]
    [-AsByteStream]
    [-NoNewLine]
    [<CommonParameters>]

DESCRIPTION

The ConvertTo-ZLibString cmdlet compresses input strings into ZLib-compressed Base64-encoded strings or raw bytes using a custom Zlib implementation built on the DeflateStream Class. For the implementation details, see the PSCompression source code. It is the counterpart to ConvertFrom-ZLibString.

EXAMPLES

Example 1: Compress strings into a ZLib-compressed Base64 string

PS ..\pwsh> $strings = 'hello', 'world', '!'
PS ..\pwsh> ConvertTo-ZLibString $strings

eJzKSM3JyeflKs8vyknh5VLk5QIAAAD//wMAMosEow==

# Or using pipeline input
PS ..\pwsh> $strings | ConvertTo-ZLibString

eJzKSM3JyeflKs8vyknh5VLk5QIAAAD//wMAMosEow==

This example shows how to compress an array of strings into a single ZLib-compressed Base64 string, using either argument or pipeline input.

Example 2: Save ZLib-compressed bytes to a file using -AsByteStream

PS ..\pwsh> 'hello world!' | ConvertTo-ZLibString -AsByteStream | Set-Content -FilePath .\helloworld.zlib -AsByteStream

# To read the file back you can use `ConvertFrom-ZLibString` following these steps:
PS ..\pwsh> $path = Convert-Path .\helloworld.zlib
PS ..\pwsh> [System.Convert]::ToBase64String([System.IO.File]::ReadAllBytes($path)) | ConvertFrom-ZLibString

hello world!

This example shows how to use -AsByteStream to output raw compressed bytes that can be written to a file using Set-Content or Out-File. Note that the byte array is not enumerated.

Note

The example uses -AsByteStream with Set-Content, which is available in PowerShell 7+. In Windows PowerShell 5.1, use -Encoding Byte with Set-Content or Out-File to write the byte array to a file.

Example 3: Compress strings using a specific Encoding

PS ..\pwsh> 'ñ' | ConvertTo-ZLibString -Encoding ansi | ConvertFrom-ZLibString
�

PS ..\pwsh> 'ñ' | ConvertTo-ZLibString -Encoding utf8BOM | ConvertFrom-ZLibString
ñ

This example shows how different encodings affect the compression and decompression of special characters. The default encoding is utf8NoBOM.

Example 4: Compress the contents of multiple files into a single ZLib-compressed Base64 string

# Check the total length of the files
PS ..\pwsh> (Get-Content myLogs\*.txt | Measure-Object Length -Sum).Sum / 1kb
87.216796875

# Check the total length after compression
PS ..\pwsh> (Get-Content myLogs\*.txt | ConvertTo-ZLibString).Length / 1kb
35.123456789

This example demonstrates compressing the contents of multiple text files into a single ZLib-compressed Base64 string and compares the total length before and after compression.

PARAMETERS

-AsByteStream

Outputs the compressed byte array to the Success Stream.

Note

This parameter is intended for use with cmdlets that accept byte arrays, such as Out-File and Set-Content with -Encoding Byte (Windows PowerShell 5.1) or -AsByteStream (PowerShell 7+).

Type: SwitchParameter
Parameter Sets: (All)
Aliases: Raw

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-CompressionLevel

Specifies the compression level for the ZLib algorithm, balancing speed and compression size. See CompressionLevel Enum for details.

Type: CompressionLevel
Parameter Sets: (All)
Aliases:
Accepted values: Optimal, Fastest, NoCompression, SmallestSize

Required: False
Position: Named
Default value: Optimal
Accept pipeline input: False
Accept wildcard characters: False

-Encoding

Determines the character encoding used when compressing the input strings.

Note

The default encoding is UTF-8 without BOM.

Type: Encoding
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: utf8NoBOM
Accept pipeline input: False
Accept wildcard characters: False

-InputObject

Specifies the input string or strings to compress.

Type: String[]
Parameter Sets: (All)
Aliases:

Required: True
Position: 0
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False

-NoNewLine

The encoded string representations of the input objects are concatenated to form the output. No newline character is added after each input string when this switch is used.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters. For more information, see about_CommonParameters.

INPUTS

System.String[]

You can pipe one or more strings to this cmdlet.

OUTPUTS

System.String

By default, this cmdlet outputs a single Base64-encoded string.

System.Byte[]

When the -AsByteStream switch is used, this cmdlet outputs a byte array down the pipeline.

NOTES

RELATED LINKS

ConvertFrom-ZLibString

System.IO.Compression

DeflateStream Class

ZlibStream Class