0
# String Comparison
1

2
Character-by-character string comparison with unified diff output, semantic cleanup, and support for both single-line and multi-line strings.
3

4
## Capabilities
5

6
### Unified String Diff
7

8
Compares two strings character-by-character and returns formatted unified diff output.
9

10
```typescript { .api }
11
/**
12
 * Compare two strings character-by-character and format as comparison lines
13
 * in which changed substrings have inverse colors
14
 * @param a - First string to compare
15
 * @param b - Second string to compare
16
 * @param options - Optional formatting configuration
17
 * @returns Formatted unified diff string
18
 */
19
function diffStringsUnified(a: string, b: string, options?: DiffOptions): string;
20
```
21

22
**Features:**
23
- **Multiline Detection**: Automatically detects multiline strings and appends newlines for proper alignment
24
- **Character-level Highlighting**: Shows exact character differences with color highlighting
25
- **Common Substring Detection**: Identifies and preserves common substrings for readability
26
- **Fallback Handling**: Falls back to line-by-line diff when character diff isn't meaningful
27

28
**Usage Examples:**
29

30
```typescript
31
import { diffStringsUnified } from "jest-diff";
32

33
// Single-line strings
34
const result1 = diffStringsUnified("Hello world", "Hello Jest");
35
console.log(result1);
36

37
// Multi-line strings
38
const text1 = `Line 1
39
Line 2
40
Line 3`;
41
const text2 = `Line 1
42
Modified Line 2
43
Line 3`;
44
const result2 = diffStringsUnified(text1, text2);
45
console.log(result2);
46

47
// With custom options
48
const result3 = diffStringsUnified("old text", "new text", {
49
  aAnnotation: "Original",
50
  bAnnotation: "Updated", 
51
  contextLines: 2
52
});
53
console.log(result3);
54
```
55

56
### Raw String Diff
57

58
Compares two strings character-by-character and returns raw diff operations array.
59

60
```typescript { .api }
61
/**
62
 * Compare two strings character-by-character and return raw diff operations
63
 * @param a - First string to compare
64
 * @param b - Second string to compare
65
 * @param cleanup - Whether to apply semantic cleanup to improve diff quality
66
 * @returns Array of Diff objects representing the operations
67
 */
68
function diffStringsRaw(a: string, b: string, cleanup: boolean): Array<Diff>;
69
```
70

71
**Cleanup Process:**
72
- **Semantic Cleanup**: When enabled, eliminates semantically trivial equalities and improves diff readability
73
- **Overlap Detection**: Finds overlaps between deletions and insertions to reduce noise
74
- **Boundary Alignment**: Aligns edits to word and line boundaries where possible
75

76
**Usage Examples:**
77

78
```typescript
79
import { diffStringsRaw, DIFF_DELETE, DIFF_INSERT, DIFF_EQUAL } from "jest-diff";
80

81
// Basic usage with cleanup
82
const diffs = diffStringsRaw("Hello world", "Hello Jest", true);
83
diffs.forEach(diff => {
84
  const [op, text] = [diff[0], diff[1]];
85
  switch (op) {
86
    case DIFF_DELETE:
87
      console.log(`Delete: "${text}"`);
88
      break;
89
    case DIFF_INSERT:
90
      console.log(`Insert: "${text}"`);
91
      break;
92
    case DIFF_EQUAL:
93
      console.log(`Keep: "${text}"`);
94
      break;
95
  }
96
});
97

98
// Without cleanup for raw operations
99
const rawDiffs = diffStringsRaw("abc", "axc", false);
100
console.log(rawDiffs);
101
```
102

103
## Diff Operations
104

105
```typescript { .api }
106
class Diff {
107
  0: number; // Operation type
108
  1: string; // Text content
109
  constructor(op: number, text: string);
110
}
111

112
const DIFF_DELETE = -1; // Text was deleted from first string
113
const DIFF_INSERT = 1;  // Text was inserted in second string  
114
const DIFF_EQUAL = 0;   // Text is common to both strings
115
```