Skip to content

Commit

Permalink
Include null and undefined elements in flat() example (#36095)
Browse files Browse the repository at this point in the history
* Include null and undefined elements in flat() examples

- I wasn't sure if `null`, `undefined`, and "empty" were equivalent in the eyes of the `flat()` method, so I tried it out in the console and learned that they are not.
- I've modified the example for sparse arrays to include these values so that others don't have to run their own experiments to learn this information. 
- I also included a link to the sparse array documentation. If the way `flat()` handles `null` and `undefined` confuses the reader, I think they are likely to click on this link to educate themselves.

* In flat() docs, change "ignore empty slots" to "remove empty slots"

- I noticed that a later example uses the phrase "remove empty slots" in its language, otherwise I wouldn't have made this PR: 
- I think the "ignore" in "ignore empty slots" may be more technically correct, but "remove empty slots" paints a clearer picture and is harder to misinterpret. "Ignoring" an element could have meant it is returned without modification.
  • Loading branch information
DanKaplanSES authored Sep 29, 2024
1 parent bc3edf4 commit c79069d
Showing 1 changed file with 5 additions and 5 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ A new array with the sub-array elements concatenated into it.

The `flat()` method is a [copying method](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#copying_methods_and_mutating_methods). It does not alter `this` but instead returns a [shallow copy](/en-US/docs/Glossary/Shallow_copy) that contains the same elements as the ones from the original array.

The `flat()` method ignores empty slots if the array being flattened is [sparse](/en-US/docs/Web/JavaScript/Guide/Indexed_collections#sparse_arrays). For example, if `depth` is 1, both empty slots in the root array and in the first level of nested arrays are ignored, but empty slots in further nested arrays are preserved with the arrays themselves.
The `flat()` method removes empty slots if the array being flattened is [sparse](/en-US/docs/Web/JavaScript/Guide/Indexed_collections#sparse_arrays). For example, if `depth` is 1, both empty slots in the root array and in the first level of nested arrays are ignored, but empty slots in further nested arrays are preserved with the arrays themselves.

The `flat()` method is [generic](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#generic_array_methods). It only expects the `this` value to have a `length` property and integer-keyed properties. However, its elements must be arrays if they are to be flattened.

Expand Down Expand Up @@ -61,7 +61,7 @@ arr4.flat(Infinity);

### Using flat() on sparse arrays

The `flat()` method removes empty slots in arrays:
The `flat()` method removes [empty slots](/en-US/docs/Web/JavaScript/Guide/Indexed_collections#sparse_arrays) in arrays:

```js
const arr5 = [1, 2, , 4, 5];
Expand All @@ -70,9 +70,9 @@ console.log(arr5.flat()); // [1, 2, 4, 5]
const array = [1, , 3, ["a", , "c"]];
console.log(array.flat()); // [ 1, 3, "a", "c" ]

const array2 = [1, , 3, ["a", , ["d", , "e"]]];
console.log(array2.flat()); // [ 1, 3, "a", ["d", empty, "e"] ]
console.log(array2.flat(2)); // [ 1, 3, "a", "d", "e"]
const array2 = [1, , 3, undefined, ["a", , ["d", , "e"]], null];
console.log(array2.flat()); // [ 1, 3, undefined, "a", ["d", empty, "e"], null ]
console.log(array2.flat(2)); // [ 1, 3, undefined, "a", "d", "e", null ]
```

### Calling flat() on non-array objects
Expand Down

0 comments on commit c79069d

Please sign in to comment.