java/java-diff-utils
1
0
Fork 0
mirror of https://github.com/java-diff-utils/java-diff-utils.git synced 2026-03-13 10:11:17 +08:00
Code Issues Packages Projects Releases Wiki Activity

Update JavaDoc for DiffUtils class (#163)

Browse Source
This commit is contained in:
Mohammad Ali Al Salti
2023-03-21 23:54:11 +03:00
committed by GitHub
parent 9f88cf91fb
commit 02532a9720
1 changed files with 73 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

119
java-diff-utils/src/main/java/com/github/difflib/DiffUtils.java
View File

@@ -30,7 +30,7 @@ import java.util.Objects;
import java.util.function.BiPredicate;
/**
* Implements the difference and patching engine
* Utility class to implement the difference and patching engine.
*/
public final class DiffUtils {
@@ -39,38 +39,63 @@ public final class DiffUtils {
*/
static DiffAlgorithmFactory DEFAULT_DIFF = MyersDiff.factory();
/**
* Sets the default diff algorithm factory to be used by all diff routines.
*
* @param factory a {@link DiffAlgorithmFactory} represnting the new default diff algorithm factory.
*/
public static void withDefaultDiffAlgorithmFactory(DiffAlgorithmFactory factory) {
DEFAULT_DIFF = factory;
}
/**
* Computes the difference between the original and revised list of elements
* with default diff algorithm
* Computes the difference between two sequences of elements using the default diff algorithm.
*
* @param <T> types to be diffed
* @param original The original text. Must not be {@code null}.
* @param revised The revised text. Must not be {@code null}.
* @param progress progress listener
* @return The patch describing the difference between the original and
* revised sequences. Never {@code null}.
* @param <T> a generic representing the type of the elements to be compared.
* @param original a {@link List} represnting the original sequence of elements. Must not be {@code null}.
* @param revised a {@link List} represnting the revised sequence of elements. Must not be {@code null}.
* @param progress a {@link DiffAlgorithmListener} represnting the progress listener. Can be {@code null}.
* @return The patch describing the difference between the original and revised sequences. Never {@code null}.
*/
public static <T> Patch<T> diff(List<T> original, List<T> revised, DiffAlgorithmListener progress) {
return DiffUtils.diff(original, revised, DEFAULT_DIFF.create(), progress);
}
/**
* Computes the difference between two sequences of elements using the default diff algorithm.
*
* @param <T> a generic representing the type of the elements to be compared.
* @param original a {@link List} represnting the original sequence of elements. Must not be {@code null}.
* @param revised a {@link List} represnting the revised sequence of elements. Must not be {@code null}.
* @return The patch describing the difference between the original and revised sequences. Never {@code null}.
*/
public static <T> Patch<T> diff(List<T> original, List<T> revised) {
return DiffUtils.diff(original, revised, DEFAULT_DIFF.create(), null);
}
/**
* Computes the difference between two sequences of elements using the default diff algorithm.
*
* @param <T> a generic representing the type of the elements to be compared.
* @param original a {@link List} represnting the original sequence of elements. Must not be {@code null}.
* @param revised a {@link List} represnting the revised sequence of elements. Must not be {@code null}.
* @param includeEqualParts a {@link boolean} represnting whether to include equal parts in the resulting patch.
* @return The patch describing the difference between the original and revised sequences. Never {@code null}.
*/
public static <T> Patch<T> diff(List<T> original, List<T> revised, boolean includeEqualParts) {
return DiffUtils.diff(original, revised, DEFAULT_DIFF.create(), null, includeEqualParts);
}
/**
* Computes the difference between the original and revised text.
* Computes the difference between two strings using the default diff algorithm.
*
* @param sourceText a {@link String} represnting the original string. Must not be {@code null}.
* @param targetText a {@link String} represnting the revised string. Must not be {@code null}.
* @param progress a {@link DiffAlgorithmListener} represnting the progress listener. Can be {@code null}.
* @return The patch describing the difference between the original and revised strings. Never {@code null}.
*/
public static Patch<String> diff(String sourceText, String targetText,
DiffAlgorithmListener progress) {
DiffAlgorithmListener progress) {
return DiffUtils.diff(
Arrays.asList(sourceText.split("\n")),
Arrays.asList(targetText.split("\n")), progress);
@@ -80,17 +105,16 @@ public final class DiffUtils {
* Computes the difference between the original and revised list of elements
* with default diff algorithm
*
* @param source The original text. Must not be {@code null}.
* @param target The revised text. Must not be {@code null}.
*
* @param equalizer the equalizer object to replace the default compare
* @param source a {@link List} represnting the original text. Must not be {@code null}.
* @param target a {@link List} represnting the revised text. Must not be {@code null}.
* @param equalizer a {@link BiPredicate} represnting the equalizer object to replace the default compare
* algorithm (Object.equals). If {@code null} the default equalizer of the
* default algorithm is used..
* default algorithm is used.
* @return The patch describing the difference between the original and
* revised sequences. Never {@code null}.
*/
public static <T> Patch<T> diff(List<T> source, List<T> target,
BiPredicate<T, T> equalizer) {
BiPredicate<T, T> equalizer) {
if (equalizer != null) {
return DiffUtils.diff(source, target,
DEFAULT_DIFF.create(equalizer));
@@ -99,7 +123,7 @@ public final class DiffUtils {
}
public static <T> Patch<T> diff(List<T> original, List<T> revised,
DiffAlgorithmI<T> algorithm, DiffAlgorithmListener progress) {
DiffAlgorithmI<T> algorithm, DiffAlgorithmListener progress) {
return diff(original, revised, algorithm, progress, false);
}
@@ -107,17 +131,17 @@ public final class DiffUtils {
* Computes the difference between the original and revised list of elements
* with default diff algorithm
*
* @param original The original text. Must not be {@code null}.
* @param revised The revised text. Must not be {@code null}.
* @param algorithm The diff algorithm. Must not be {@code null}.
* @param progress The diff algorithm listener.
* @param original a {@link List} represnting the original text. Must not be {@code null}.
* @param revised a {@link List} represnting the revised text. Must not be {@code null}.
* @param algorithm a {@link DiffAlgorithmI} represnting the diff algorithm. Must not be {@code null}.
* @param progress a {@link DiffAlgorithmListener} represnting the diff algorithm listener.
* @param includeEqualParts Include equal data parts into the patch.
* @return The patch describing the difference between the original and
* revised sequences. Never {@code null}.
*/
public static <T> Patch<T> diff(List<T> original, List<T> revised,
DiffAlgorithmI<T> algorithm, DiffAlgorithmListener progress,
boolean includeEqualParts) {
DiffAlgorithmI<T> algorithm, DiffAlgorithmListener progress,
boolean includeEqualParts) {
Objects.requireNonNull(original, "original must not be null");
Objects.requireNonNull(revised, "revised must not be null");
Objects.requireNonNull(algorithm, "algorithm must not be null");
@@ -125,13 +149,14 @@ public final class DiffUtils {
return Patch.generate(original, revised, algorithm.computeDiff(original, revised, progress), includeEqualParts);
}
/**
* Computes the difference between the original and revised list of elements
* with default diff algorithm
*
* @param original The original text. Must not be {@code null}.
* @param revised The revised text. Must not be {@code null}.
* @param algorithm The diff algorithm. Must not be {@code null}.
* @param original a {@link List} represnting the original text. Must not be {@code null}.
* @param revised a {@link List} represnting the revised text. Must not be {@code null}.
* @param algorithm a {@link DiffAlgorithmI} represnting the diff algorithm. Must not be {@code null}.
* @return The patch describing the difference between the original and
* revised sequences. Never {@code null}.
*/
@@ -144,9 +169,10 @@ public final class DiffUtils {
* "trick" to make out of texts lists of characters, like DiffRowGenerator
* does and merges those changes at the end together again.
*
* @param original
* @param revised
* @return
* @param original a {@link String} represnting the original text. Must not be {@code null}.
* @param revised a {@link String} represnting the revised text. Must not be {@code null}.
* @return The patch describing the difference between the original and
* revised sequences. Never {@code null}.
*/
public static Patch<String> diffInline(String original, String revised) {
List<String> origList = new ArrayList<>();
@@ -165,20 +191,13 @@ public final class DiffUtils {
return patch;
}
private static List<String> compressLines(List<String> lines, String delimiter) {
if (lines.isEmpty()) {
return Collections.emptyList();
}
return Collections.singletonList(String.join(delimiter, lines));
}
/**
* Patch the original text with given patch
* Applies the given patch to the original list and returns the revised list.
*
* @param original the original text
* @param patch the given patch
* @return the revised text
* @throws PatchFailedException if can't apply patch
* @param original a {@link List} represnting the original list.
* @param patch a {@link List} represnting the patch to apply.
* @return the revised list.
* @throws PatchFailedException if the patch cannot be applied.
*/
public static <T> List<T> patch(List<T> original, Patch<T> patch)
throws PatchFailedException {
@@ -186,16 +205,24 @@ public final class DiffUtils {
}
/**
* Unpatch the revised text for a given patch
* Applies the given patch to the revised list and returns the original list.
*
* @param revised the revised text
* @param patch the given patch
* @return the original text
* @param revised a {@link List} represnting the revised list.
* @param patch a {@link Patch} represnting the patch to apply.
* @return the original list.
* @throws PatchFailedException if the patch cannot be applied.
*/
public static <T> List<T> unpatch(List<T> revised, Patch<T> patch) {
return patch.restore(revised);
}
private static List<String> compressLines(List<String> lines, String delimiter) {
if (lines.isEmpty()) {
return Collections.emptyList();
}
return Collections.singletonList(String.join(delimiter, lines));
}
private DiffUtils() {
}
}