0
# lodash.take
1

2
The lodash method `_.take` exported as a standalone Node.js module. Creates a slice of an array with n elements taken from the beginning, providing efficient array slicing with comprehensive edge case handling.
3

4
## Package Information
5

6
- **Package Name**: lodash.take
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install lodash.take`
10

11
## Core Imports
12

13
```javascript
14
var take = require('lodash.take');
15
```
16

17
For ES6 modules (requires transpilation or bundler):
18

19
```javascript
20
import take from 'lodash.take';
21
```
22

23
## Basic Usage
24

25
```javascript
26
var take = require('lodash.take');
27

28
// Take the first element (default behavior)
29
take([1, 2, 3]);
30
// => [1]
31

32
// Take multiple elements
33
take([1, 2, 3, 4, 5], 3);
34
// => [1, 2, 3]
35

36
// Handle edge cases gracefully
37
take([1, 2, 3], 10);  // More than available
38
// => [1, 2, 3]
39

40
take([1, 2, 3], 0);   // Take zero elements
41
// => []
42

43
take([], 5);          // Empty array
44
// => []
45
```
46

47
## Capabilities
48

49
### Array Slicing
50

51
Creates a slice of array with n elements taken from the beginning.
52

53
```javascript { .api }
54
/**
55
 * Creates a slice of array with n elements taken from the beginning.
56
 * @param {Array} array - The array to query. If empty or falsy, returns empty array.
57
 * @param {number} [n=1] - The number of elements to take from the beginning. Defaults to 1 if not provided or undefined.
58
 * @param {Object} [guard] - Internal parameter that enables use as an iteratee for methods like _.map. When present, forces n to default to 1.
59
 * @returns {Array} Returns a new array containing the specified number of elements from the start of the input array.
60
 */
61
function take(array, n, guard);
62
```
63

64
**Parameters:**
65
- `array` (Array): The array to query. If empty or falsy, returns empty array.
66
- `n` (number, optional): The number of elements to take from the beginning. Defaults to 1 if not provided or undefined.
67
- `guard` (Object, optional): Internal parameter that enables use as an iteratee for methods like `_.map`. When present, forces `n` to default to 1.
68

69
**Returns:**
70
- (Array): Returns a new array containing the specified number of elements from the start of the input array.
71

72
**Behavior:**
73
- Returns empty array if input array is empty, null, or undefined
74
- Negative values for `n` are treated as 0, returning empty array
75
- Values of `n` larger than array length return the entire array
76
- Always returns a new array (does not mutate the original)
77
- Uses efficient internal slicing implementation for performance
78

79
**Usage Examples:**
80

81
```javascript
82
var take = require('lodash.take');
83

84
// Basic usage
85
take([1, 2, 3]);
86
// => [1]
87

88
take([1, 2, 3], 2);
89
// => [1, 2]
90

91
// Edge cases
92
take([1, 2, 3], 5);   // More than array length
93
// => [1, 2, 3]
94

95
take([1, 2, 3], 0);   // Zero elements
96
// => []
97

98
take([1, 2, 3], -1);  // Negative number
99
// => []
100

101
take(null, 3);        // Null/undefined input
102
// => []
103

104
take([], 3);          // Empty array
105
// => []
106

107
// Works with different array types
108
take(['a', 'b', 'c', 'd'], 2);
109
// => ['a', 'b']
110

111
take([true, false, true], 1);
112
// => [true]
113
```
114

115
**Performance Characteristics:**
116
- O(n) time complexity where n is the number of elements to take
117
- O(n) space complexity for the returned array
118
- Optimized internal implementation using bitwise operations
119
- No external dependencies - fully self-contained module