textdiff

Documentation

Overview

Package textdiff provides functions to efficiently compare text line-by-line.

This package is specialized for text comparison and provides unified diff output like the Unix diff command. The main functions are Hunks for grouped changes, Edits for individual changes, and Unified for standard diff format output.

Performance: Default complexity is O(N^1.5 log N) time and O(N) space. With [Optimal], time complexity becomes O(ND) where N = len(x) + len(y) and D is the number of edits.

Index

• func IndentHeuristic() diff.Option
• func Unified[T string | []byte](x, y T, opts ...diff.Option) T
• type Edit
  • func Edits[T string | []byte](x, y T, opts ...diff.Option) []Edit[T]
• type Hunk
  • func Hunks[T string | []byte](x, y T, opts ...diff.Option) []Hunk[T]

Examples

• IndentHeuristic
• Unified

Functions

func IndentHeuristic

func IndentHeuristic() diff.Option

IndentHeuristic applies a heuristic to make diffs easier to read by improving the placement of edit boundaries.

This implements a heuristic that shifts edit boundaries to align with indentation patterns, making the resulting diff more readable for humans. The heuristic is particularly effective with code and structured text.

Example

package main

import (
	"fmt"

	"znkr.io/diff/textdiff"
)

func main() {
	x := `// ...
["foo", "bar", "baz"].map do |i|
  i.upcase
end
`

	y := `// ...
["foo", "bar", "baz"].map do |i|
  i
end

["foo", "bar", "baz"].map do |i|
  i.upcase
end
`

	fmt.Println("With textdiff.IndentHeuristic:")
	fmt.Print(textdiff.Unified(x, y, textdiff.IndentHeuristic()))
	fmt.Println()
	fmt.Println("Without textdiff.IndentHeuristic:")
	fmt.Print(textdiff.Unified(x, y))
}

Output:

With textdiff.IndentHeuristic:
@@ -1,4 +1,8 @@
 // ...
+["foo", "bar", "baz"].map do |i|
+  i
+end
+
 ["foo", "bar", "baz"].map do |i|
   i.upcase
 end

Without textdiff.IndentHeuristic:
@@ -1,4 +1,8 @@
 // ...
 ["foo", "bar", "baz"].map do |i|
+  i
+end
+
+["foo", "bar", "baz"].map do |i|
   i.upcase
 end

func Unified

func Unified[T string | []byte](x, y T, opts ...diff.Option) T

Unified compares the lines in x and y and returns the changes necessary to convert from one to the other in unified format.

The following options are supported: diff.Context, diff.Optimal, diff.Fast, textdiff.IndentHeuristic

Important: The output is not guaranteed to be stable and may change with minor version upgrades. DO NOT rely on the output being stable.

Example

package main

import (
	"fmt"

	"znkr.io/diff/textdiff"
)

func main() {
	x := `this paragraph
is not
changed and
barely long
enough to
create a
new hunk

this paragraph
is going to be
removed
`

	y := `this is a new paragraph
that is inserted at the top

this paragraph
is not
changed and
barely long
enough to
create a
new hunk
`
	fmt.Print(textdiff.Unified(x, y))
}

Output:

@@ -1,3 +1,6 @@
+this is a new paragraph
+that is inserted at the top
+
 this paragraph
 is not
 changed and
@@ -5,7 +8,3 @@
 enough to
 create a
 new hunk
-
-this paragraph
-is going to be
-removed

Types

type Edit

type Edit[T string | []byte] struct {
	Op   diff.Op
	Line T
}

Edit describes a single edit of a line-by-line diff.

func Edits

func Edits[T string | []byte](x, y T, opts ...diff.Option) []Edit[T]

Edits compares the lines in x and y and returns the changes necessary to convert from one to the other.

Edits returns edits for every element in the input. If x and y are identical, the output will consist of a match edit for every input element.

The following options are supported: diff.Optimal, diff.Fast, textdiff.IndentHeuristic

Important: The output is not guaranteed to be stable and may change with minor version upgrades. DO NOT rely on the output being stable.

type Hunk

type Hunk[T string | []byte] struct {
	PosX, EndX int       // Start and end position in x.
	PosY, EndY int       // Start and end position in y.
	Edits      []Edit[T] // Edits to transform x[PosX:EndX] to y[PosY:EndY]
}

Hunk describes a sequence of consecutive edits.

func Hunks

func Hunks[T string | []byte](x, y T, opts ...diff.Option) []Hunk[T]

Hunks compares the lines in x and y and returns the changes necessary to convert from one to the other.

The output is a sequence of hunks that each describe a number of consecutive edits. Hunks include a number of matching elements before and after the last delete or insert operation. The number of elements can be configured using [Context].

If x and y are identical, the output has length zero.

The following options are supported: diff.Context, diff.Optimal, diff.Fast, textdiff.IndentHeuristic

Important: The output is not guaranteed to be stable and may change with minor version upgrades. DO NOT rely on the output being stable.