Skip to content

Update JavaDoc for DiffUtils class #163

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 21, 2023
Merged

Update JavaDoc for DiffUtils class #163

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 73 additions & 46 deletions java-diff-utils/src/main/java/com/github/difflib/DiffUtils.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@
import java.util.function.BiPredicate;

/**
* Implements the difference and patching engine
* Utility class to implement the difference and patching engine.
*/
public final class DiffUtils {

Expand All @@ -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);
Expand All @@ -80,17 +105,16 @@ public static Patch<String> diff(String sourceText, String targetText,
* 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));
Expand All @@ -99,39 +123,40 @@ public static <T> Patch<T> diff(List<T> source, List<T> target,
}

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);
}

/**
* 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");

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}.
*/
Expand All @@ -144,9 +169,10 @@ public static <T> Patch<T> diff(List<T> original, List<T> revised, DiffAlgorithm
* "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<>();
Expand All @@ -165,37 +191,38 @@ public static Patch<String> diffInline(String original, String revised) {
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 {
return patch.applyTo(original);
}

/**
* 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() {
}
}