0
# lodash.trim
1

2
The lodash method `_.trim` exported as a Node.js module for removing leading and trailing whitespace or specified characters from strings with comprehensive Unicode support.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const trim = require('lodash.trim');
15
```
16

17
For ES modules (if your environment supports it):
18

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

23
## Basic Usage
24

25
```javascript
26
const trim = require('lodash.trim');
27

28
// Trim whitespace from both ends
29
const result1 = trim('  hello world  ');
30
// => 'hello world'
31

32
// Trim specific characters
33
const result2 = trim('-_-abc-_-', '_-');
34
// => 'abc'
35

36
// Works with Unicode characters
37
const result3 = trim('  café  ');
38
// => 'café'
39

40
// Use as iteratee function
41
const inputs = ['  foo  ', '  bar  '];
42
const cleaned = inputs.map(trim);
43
// => ['foo', 'bar']
44
```
45

46
## Capabilities
47

48
### String Trimming
49

50
Removes leading and trailing whitespace or specified characters from strings with advanced Unicode support. When used as an iteratee function (e.g., with `map`), only whitespace trimming is performed regardless of the `chars` parameter.
51

52
```javascript { .api }
53
/**
54
 * Removes leading and trailing whitespace or specified characters from string.
55
 * @param {string} string - The string to trim. Null/undefined values are converted to empty string.
56
 * @param {string} chars - The characters to trim. When omitted, trims all whitespace characters.
57
 * @returns {string} Returns the trimmed string
58
 */
59
function trim(string, chars);
60
```
61

62
**Parameters:**
63

64
- **`string`** *(string)*: The string to trim. Null and undefined values are automatically converted to empty string.
65
- **`chars`** *(string, optional)*: The characters to trim from both ends. When not provided, trims all whitespace characters including Unicode whitespace.
66

67
**Returns:**
68

69
*(string)*: The trimmed string with specified characters or whitespace removed from both ends.
70

71
**Usage Examples:**
72

73
```javascript
74
const trim = require('lodash.trim');
75

76
// Basic whitespace trimming
77
trim('  hello  ');
78
// => 'hello'
79

80
// Custom character trimming
81
trim('__hello__', '_');
82
// => 'hello'
83

84
// Multiple custom characters
85
trim('-_-hello-_-', '_-');
86
// => 'hello'
87

88
// Unicode whitespace support
89
trim('\u2000\u2001hello\u2002\u2003');
90
// => 'hello'
91

92
// Complex Unicode characters with combining marks
93
trim('  café\u0301  ');  // é with combining acute accent
94
// => 'café\u0301'
95

96
// Empty string handling
97
trim('');
98
// => ''
99

100
// Null/undefined handling
101
trim(null);
102
// => ''
103
trim(undefined);
104
// => ''
105

106
// Use as iteratee (only trims whitespace when used this way)
107
['  foo  ', '  bar  ', '  baz  '].map(trim);
108
// => ['foo', 'bar', 'baz']
109

110
// Note: When used as an iteratee function, custom chars parameter is ignored
111
['__foo__', '__bar__', '__baz__'].map(trim);
112
// => ['__foo__', '__bar__', '__baz__'] (underscores not removed)
113
```
114

115
## Advanced Features
116

117
### Unicode Support
118

119
The trim function provides comprehensive Unicode support including:
120

121
- **Astral Plane Characters**: Properly handles characters beyond the Basic Multilingual Plane (BMP)
122
- **Combining Characters**: Correctly processes combining marks and diacritical marks
123
- **Zero-Width Joiners**: Supports complex emoji and character sequences with ZWJ
124
- **Surrogate Pairs**: Handles high and low surrogate pairs for extended Unicode characters
125
- **Regional Indicators**: Properly processes flag emoji and regional sequences
126
- **Fitzpatrick Modifiers**: Supports skin tone modifiers for emoji characters
127

128
### Performance Optimization
129

130
The function uses different processing strategies based on string content:
131

132
- **ASCII-only strings**: Uses faster character-by-character processing
133
- **Unicode strings**: Employs sophisticated Unicode-aware parsing to maintain character integrity
134
- **Whitespace-only trimming**: Optimized regex-based approach for default behavior
135

136
### Cross-Platform Compatibility
137

138
The module works consistently across different JavaScript environments:
139

140
- **Node.js**: Full compatibility with all Node.js versions
141
- **Browsers**: Works in modern browsers with proper Unicode support
142
- **Global Detection**: Automatically detects and adapts to different global object patterns
143

144
## Error Handling
145

146
The function gracefully handles edge cases:
147

148
- **Null/undefined inputs**: Converts to empty string
149
- **Non-string inputs**: Converts to string using internal `toString` implementation
150
- **Symbol inputs**: Properly converts Symbol values to string representation
151
- **Invalid Unicode sequences**: Handles malformed Unicode gracefully
152

153
## Type Conversion
154

155
Input values are automatically converted to strings using lodash's internal `toString` function:
156

157
- Numbers: `42` becomes `"42"`
158
- Booleans: `true` becomes `"true"`
159
- Arrays: `[1,2,3]` becomes `"1,2,3"`
160
- Objects: Uses `Object.prototype.toString` or custom `toString` methods
161
- Symbols: Converts to string representation using `Symbol.prototype.toString`
162
- Null/undefined: Becomes empty string `""`
163
- `-0`: Preserves the sign and becomes `"-0"`