Skip to content

Commit

Permalink
(GH-11175) Update terminology to 'enumerable null' (#11177)
Browse files Browse the repository at this point in the history
Prior to this change, the article 'Everything you wanted to know about `$null`'
used the term 'empty `$null`' to describe
`[System.Management.Automation.Internal.AutomationNull]::Value`

However, this terminology isn't clear enough, as both that value and the `$null`
value itself can be considered to be 'empty.'

This change:

- Updates to use the terminology 'enumerable null' instead of 'empty `$null`'
  to describe the value.
- Resolves #11175
- Fixes AB#260888
  • Loading branch information
michaeltlombardi committed Jun 11, 2024
1 parent 9672a80 commit 6d5d3c5
Showing 1 changed file with 18 additions and 16 deletions.
34 changes: 18 additions & 16 deletions reference/docs-conceptual/learn/deep-dives/everything-about-null.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
description: The PowerShell $null often appears to be simple but it has a lot of nuances. Let's take a close look at $null so you know what happens when you unexpectedly run into a null value.
ms.custom: contributor-KevinMarquette
ms.date: 11/16/2022
ms.date: 06/11/2024
title: Everything you wanted to know about $null
---
# Everything you wanted to know about $null
Expand Down Expand Up @@ -298,12 +298,13 @@ if ( $value.count -eq 1 )
}
```

## Empty null
## Enumerable null

There is one special type of `$null` that acts differently than the others. I am going to call it
the empty `$null` but it's really a [System.Management.Automation.Internal.AutomationNull][System.Management.Automation.Internal.AutomationNull]. This
empty `$null` is the one you get as the result of a function or script block that returns nothing (a
void result).
the enumerable null but it's really a
[System.Management.Automation.Internal.AutomationNull][System.Management.Automation.Internal.AutomationNull].
This enumerable null is the one you get as the result of a function or script block that returns
nothing (a void result).

```powershell
PS> function Get-Nothing {}
Expand All @@ -330,18 +331,19 @@ PS> $containnull.count
```

You can have an array that contains one `$null` value and its `count` is `1`. But if you place
an empty result inside an array then it's not counted as an item. The count is `0`.
an empty array inside an array then it's not counted as an item. The count is `0`.

If you treat the empty `$null` like a collection, then it's empty.
If you treat the enumerable null like a collection, then it's empty.

If you pass in an empty value to a function parameter that isn't strongly typed, PowerShell coerces
the nothing value into a `$null` value by default. This means inside the function, the value will be
treated as `$null` instead of the **System.Management.Automation.Internal.AutomationNull** type.
If you pass in an enumerable null to a function parameter that isn't strongly typed, PowerShell
coerces the enumerable null into a `$null` value by default. This means inside the function, the
value is treated as `$null` instead of the **System.Management.Automation.Internal.AutomationNull**
type.

### Pipeline

The primary place you see the difference is when using the pipeline. You can pipe a `$null`
value but not an empty `$null` value.
value but not an enumerable null value.

```powershell
PS> $null | ForEach-Object{ Write-Output 'NULL Value' }
Expand Down Expand Up @@ -476,9 +478,9 @@ those scenarios earlier in this post.
### No results scenario

It's important to know that different functions and commands handle the no results scenario
differently. Many PowerShell commands return the empty `$null` and an error in the error stream. But
others throw exceptions or give you a status object. It's still up to you to know how the commands
you use deal with the no results and error scenarios.
differently. Many PowerShell commands return the enumerable null and an error in the error stream.
But others throw exceptions or give you a status object. It's still up to you to know how the
commands you use deal with the no results and error scenarios.

## Initializing to $null

Expand Down Expand Up @@ -511,8 +513,8 @@ function Do-Something
}
```

The expectation here is that `Get-Something` returns either a result or an empty `$null`. If there
is an error, we log it. Then we check to make sure we got a valid result before processing it.
The expectation here is that `Get-Something` returns either a result or an enumerable null. If
there's an error, we log it. Then we check to make sure we got a valid result before processing it.

The bug hiding in this code is when `Get-Something` throws an exception and doesn't assign a value
to `$result`. It fails before the assignment so we don't even assign `$null` to the `$result`
Expand Down

0 comments on commit 6d5d3c5

Please sign in to comment.