diff --git a/content/javascript/concepts/arrays/terms/flat/flat.md b/content/javascript/concepts/arrays/terms/flat/flat.md new file mode 100644 index 00000000000..9158ef2f8d7 --- /dev/null +++ b/content/javascript/concepts/arrays/terms/flat/flat.md @@ -0,0 +1,143 @@ +--- +Title: 'flat()' +Description: 'Creates a new array with all sub-array elements recursively concatenated into it up to the specified depth.' +Subjects: + - 'Computer Science' + - 'Web Development' +Tags: + - 'Arrays' + - 'Methods' +CatalogContent: + - 'introduction-to-javascript' + - 'paths/front-end-engineer-career-path' +--- + +The **`flat()`** method creates a new [array](https://www.codecademy.com/resources/docs/javascript/arrays) with sub-array elements concatenated into it up to the specified depth. It is a non-mutating method, meaning it returns a new array without modifying the original one. + +## Syntax + +```pseudo +array.flat(depth); +``` + +**Parameters:** + +- `depth` (optional): The number of levels to flatten. Defaults to `1`. Use `Infinity` to flatten all nested arrays completely. + +**Return value:** + +A new array with the sub-array elements flattened up to the specified depth. The original array remains unchanged. + +## Example 1: Using `flat()` With Default Value + +This example demonstrates using `flat()` with the default depth of `1`: + +```js +const arr = [1, 2, [3, 4]]; +console.log(arr.flat()); +``` + +The output of this code is: + +```shell +[1, 2, 3, 4] +``` + +`arr.flat()` flattens one level deep, so the nested array `[3, 4]` is unpacked into the main array. + +## Example 2: Using `flat()` on Deeper Nested Arrays + +This example demonstrates using `flat()` with the default depth of `1`, with multiple layers of nested sub-arrays: + +```js +const arr = [1, 2, 3, [4, 5, [6, 7]]]; +console.log(arr.flat()); +``` + +The output of this code is: + +```shell +[1, 2, 3, 4, 5, [6, 7]] +``` + +`arr.flat()` flattens the array one level deep. It unpacks the first-level nested array `[4, 5, [6, 7]]`, moving its elements into the main array. However, the inner array `[6, 7]` remains nested at a deeper level. + +## Example 3: Using `flat()` with a Specified Depth + +This example demonstrates using `flat()` with a depth of `2`, applied to an array with multiple layers of nested sub-arrays: + +```js +const arr = [1, 2, 3, [4, 5, [6, 7]]]; +console.log(arr.flat(2)); +``` + +The output of this code is: + +```shell +[ + 1, 2, 3, 4, + 5, 6, 7 +] +``` + +`arr.flat(2)` flattens the array two levels deep. First, it unpacks the first-level nested array `[4, 5, [6, 7]]`, moving its elements into the main array. Then, the inner array `[6, 7]` is unpacked, resulting in an entirely flattened array with no nested sub-arrays. + +## Example 4: Using `flat()` with `Infinity` Depth + +This example demonstrates using `flat()` with a depth of `Infinity`, which fully flattens an array no matter how deeply nested its sub-arrays are: + +```js +const arr = [1, [2, [3, [4, [5]]]]]; +console.log(arr.flat(Infinity)); +``` + +The output of this code is: + +```shell +[1, 2, 3, 4, 5] +``` + +`arr.flat(Infinity)` recursively flattens the array to its deepest level. All nested sub-arrays, no matter how deeply they are nested, are unpacked into a single flat array. This is useful when the depth of nesting is unknown or highly variable. + +## Example 5: Using `flat()` on Sparse Arrays with Empty Slots + +This example demonstrates using `flat()` on sparse arrays: + +```js +const arr = [1, 2, , [4, , 6], 7]; +console.log(arr.flat()); +``` + +The output of the code is: + +```shell +[1, 2, 4, 6, 7] +``` + +`flat()` removes empty slots (holes) in sparse arrays during flattening, treating them as if they don't exist. + +## Example 6: Flattening Arrays with Mixed Element Types + +The `flat()` method only flattens nested arrays. Elements that are not arrays remain the same: + +```js +const arr = [1, 'hello', [2, 3], { a: 4 }]; +console.log(arr.flat()); +``` + +The output of the code is: + +```shell +[1, "hello", 2, 3, { a: 4 }] +``` + +## Codebyte Example + +The following code demonstrates how different `.flat()` depths affect an array: + +```codebyte/js +const arr = [1, 'hello', [2, 3, [4, [5, 'world']]], { a: 4 }]; +console.log('depth = default (1) : ', arr.flat()); +console.log('depth = 2 : ', arr.flat(2)); +console.log('depth = Infinity : ', arr.flat(Infinity)); +```