diff --git a/csharp/DiffMatchPatch.cs b/csharp/DiffMatchPatch.cs index 6e196418..7393fee2 100644 --- a/csharp/DiffMatchPatch.cs +++ b/csharp/DiffMatchPatch.cs @@ -25,7 +25,15 @@ namespace DiffMatchPatch { internal static class CompatibilityExtensions { - // JScript splice function + /// + /// JScript splice function + /// + /// + /// + /// + /// + /// + /// public static List Splice(this List input, int start, int count, params T[] objects) { List deletedRange = input.GetRange(start, count); @@ -35,57 +43,68 @@ public static List Splice(this List input, int start, int count, return deletedRange; } - // Java substring function + /// + /// Java substring function + /// + /// + /// + /// + /// public static string JavaSubstring(this string s, int begin, int end) { return s.Substring(begin, end - begin); } } - /**- - * The data structure representing a diff is a List of Diff objects: - * {Diff(Operation.DELETE, "Hello"), Diff(Operation.INSERT, "Goodbye"), - * Diff(Operation.EQUAL, " world.")} - * which means: delete "Hello", add "Goodbye" and keep " world." - */ + /// + /// The data structure representing a diff is a List of Diff objects: + /// {Diff(Operation.DELETE, "Hello"), Diff(Operation.INSERT, "Goodbye"), + /// Diff(Operation.EQUAL, " world.")} + /// which means: delete "Hello", add "Goodbye" and keep " world." + /// public enum Operation { DELETE, INSERT, EQUAL } - /** - * Class representing one diff operation. - */ + /// + /// Class representing one diff operation. + /// public class Diff { + /// + /// One of: INSERT, DELETE or EQUAL. + /// public Operation operation; - // One of: INSERT, DELETE or EQUAL. + + /// + /// The text associated with this diff operation. + /// public string text; - // The text associated with this diff operation. - /** - * Constructor. Initializes the diff with the provided values. - * @param operation One of INSERT, DELETE or EQUAL. - * @param text The text being applied. - */ + /// + /// Constructor. Initializes the diff with the provided values. + /// + /// One of INSERT, DELETE or EQUAL. + /// The text being applied. public Diff(Operation operation, string text) { // Construct a diff with the specified operation and text. this.operation = operation; this.text = text; } - /** - * Display a human-readable version of this Diff. - * @return text version. - */ + /// + /// Display a human-readable version of this Diff. + /// + /// text version. public override string ToString() { string prettyText = this.text.Replace('\n', '\u00b6'); return "Diff(" + this.operation + ",\"" + prettyText + "\")"; } - /** - * Is this Diff equivalent to another Diff? - * @param d Another Diff to compare against. - * @return true or false. - */ + /// + /// Is this Diff equivalent to another Diff? + /// + /// Another Diff to compare against. + /// true or false. public override bool Equals(Object obj) { // If parameter is null return false. if (obj == null) { @@ -118,9 +137,9 @@ public override int GetHashCode() { } - /** - * Class representing one patch operation. - */ + /// + /// Class representing one patch operation. + /// public class Patch { public List diffs = new List(); public int start1; @@ -128,12 +147,12 @@ public class Patch { public int length1; public int length2; - /** - * Emulate GNU diff's format. - * Header: @@ -382,8 +481,9 @@ - * Indices are printed as 1-based, not 0-based. - * @return The GNU diff string. - */ + /// + /// Emulate GNU diff's format. + /// Header: @@ -382,8 +481,9 @@ + /// Indices are printed as 1-based, not 0-based. + /// + /// The GNU diff string. public override string ToString() { string coords1, coords2; if (this.length1 == 0) { @@ -174,61 +193,80 @@ public override string ToString() { } - /** - * Class containing the diff, match and patch methods. - * Also Contains the behaviour settings. - */ + /// + /// Class containing the diff, match and patch methods. + /// Also Contains the behaviour settings. + /// public class diff_match_patch { // Defaults. // Set these on your diff_match_patch instance to override the defaults. - // Number of seconds to map a diff before giving up (0 for infinity). + /// + /// Number of seconds to map a diff before giving up (0 for infinity). + /// public float Diff_Timeout = 1.0f; - // Cost of an empty edit operation in terms of edit characters. + + /// + /// Cost of an empty edit operation in terms of edit characters. + /// public short Diff_EditCost = 4; - // At what point is no match declared (0.0 = perfection, 1.0 = very loose). + + /// + /// At what point is no match declared (0.0 = perfection, 1.0 = very loose). + /// public float Match_Threshold = 0.5f; - // How far to search for a match (0 = exact location, 1000+ = broad match). - // A match this many characters away from the expected location will add - // 1.0 to the score (0.0 is a perfect match). + + /// + /// How far to search for a match (0 = exact location, 1000+ = broad match). + /// A match this many characters away from the expected location will add + /// 1.0 to the score (0.0 is a perfect match). + /// public int Match_Distance = 1000; - // When deleting a large block of text (over ~64 characters), how close - // do the contents have to be to match the expected contents. (0.0 = - // perfection, 1.0 = very loose). Note that Match_Threshold controls - // how closely the end points of a delete need to match. + + /// + /// When deleting a large block of text (over ~64 characters), how close + /// do the contents have to be to match the expected contents. (0.0 = + /// perfection, 1.0 = very loose). Note that Match_Threshold controls + /// how closely the end points of a delete need to match. + /// public float Patch_DeleteThreshold = 0.5f; - // Chunk size for context length. + + /// + /// Chunk size for context length. + /// public short Patch_Margin = 4; - // The number of bits in an int. + /// + /// The number of bits in an int. + /// private short Match_MaxBits = 32; // DIFF FUNCTIONS - /** - * Find the differences between two texts. - * Run a faster, slightly less optimal diff. - * This method allows the 'checklines' of diff_main() to be optional. - * Most of the time checklines is wanted, so default to true. - * @param text1 Old string to be diffed. - * @param text2 New string to be diffed. - * @return List of Diff objects. - */ + /// + /// Find the differences between two texts. + /// Run a faster, slightly less optimal diff. + /// This method allows the 'checklines' of diff_main() to be optional. + /// Most of the time checklines is wanted, so default to true. + /// + /// Old string to be diffed. + /// New string to be diffed. + /// List of Diff objects. public List diff_main(string text1, string text2) { return diff_main(text1, text2, true); } - /** - * Find the differences between two texts. - * @param text1 Old string to be diffed. - * @param text2 New string to be diffed. - * @param checklines Speedup flag. If false, then don't run a - * line-level diff first to identify the changed areas. - * If true, then run a faster slightly less optimal diff. - * @return List of Diff objects. - */ + /// + /// Find the differences between two texts. + /// + /// Old string to be diffed. + /// New string to be diffed. + /// Speedup flag. If false, then don't run a + /// line-level diff first to identify the changed areas. + /// If true, then run a faster slightly less optimal diff. + /// List of Diff objects. public List diff_main(string text1, string text2, bool checklines) { // Set a deadline by which time the diff must be complete. DateTime deadline; @@ -241,19 +279,23 @@ public List diff_main(string text1, string text2, bool checklines) { return diff_main(text1, text2, checklines, deadline); } - /** - * Find the differences between two texts. Simplifies the problem by - * stripping any common prefix or suffix off the texts before diffing. - * @param text1 Old string to be diffed. - * @param text2 New string to be diffed. - * @param checklines Speedup flag. If false, then don't run a - * line-level diff first to identify the changed areas. - * If true, then run a faster slightly less optimal diff. - * @param deadline Time when the diff should be complete by. Used - * internally for recursive calls. Users should set DiffTimeout - * instead. - * @return List of Diff objects. - */ + /// + /// Find the differences between two texts. Simplifies the problem by + /// stripping any common prefix or suffix off the texts before diffing. + /// + /// Old string to be diffed. + /// New string to be diffed. + /// + /// Speedup flag. If false, then don't run a + /// line-level diff first to identify the changed areas. + /// If true, then run a faster slightly less optimal diff. + /// + /// + /// Time when the diff should be complete by. Used + /// internally for recursive calls. Users should set DiffTimeout + /// instead. + /// + /// List of Diff objects. private List diff_main(string text1, string text2, bool checklines, DateTime deadline) { // Check for null inputs not needed since null can't be passed in C#. @@ -295,17 +337,19 @@ private List diff_main(string text1, string text2, bool checklines, return diffs; } - /** - * Find the differences between two texts. Assumes that the texts do not - * have any common prefix or suffix. - * @param text1 Old string to be diffed. - * @param text2 New string to be diffed. - * @param checklines Speedup flag. If false, then don't run a - * line-level diff first to identify the changed areas. - * If true, then run a faster slightly less optimal diff. - * @param deadline Time when the diff should be complete by. - * @return List of Diff objects. - */ + /// + /// Find the differences between two texts. Assumes that the texts do not + /// have any common prefix or suffix. + /// + /// Old string to be diffed. + /// New string to be diffed. + /// + /// Speedup flag. If false, then don't run a + /// line-level diff first to identify the changed areas. + /// If true, then run a faster slightly less optimal diff. + /// + /// Time when the diff should be complete by. + /// List of Diff objects. private List diff_compute(string text1, string text2, bool checklines, DateTime deadline) { List diffs = new List(); @@ -369,15 +413,15 @@ private List diff_compute(string text1, string text2, return diff_bisect(text1, text2, deadline); } - /** - * Do a quick line-level diff on both strings, then rediff the parts for - * greater accuracy. - * This speedup can produce non-minimal diffs. - * @param text1 Old string to be diffed. - * @param text2 New string to be diffed. - * @param deadline Time when the diff should be complete by. - * @return List of Diff objects. - */ + /// + /// Do a quick line-level diff on both strings, then rediff the parts for + /// greater accuracy. + /// This speedup can produce non-minimal diffs. + /// + /// Old string to be diffed. + /// New string to be diffed. + /// Time when the diff should be complete by. + /// List of Diff objects. private List diff_lineMode(string text1, string text2, DateTime deadline) { // Scan the text on a line-by-line basis first. @@ -436,15 +480,15 @@ private List diff_lineMode(string text1, string text2, return diffs; } - /** - * Find the 'middle snake' of a diff, split the problem in two - * and return the recursively constructed diff. - * See Myers 1986 paper: An O(ND) Difference Algorithm and Its Variations. - * @param text1 Old string to be diffed. - * @param text2 New string to be diffed. - * @param deadline Time at which to bail if not yet complete. - * @return List of Diff objects. - */ + /// + /// Find the 'middle snake' of a diff, split the problem in two + /// and return the recursively constructed diff. + /// See Myers 1986 paper: An O(ND) Difference Algorithm and Its Variations. + /// + /// Old string to be diffed. + /// New string to be diffed. + /// Time at which to bail if not yet complete. + /// List of Diff objects. protected List diff_bisect(string text1, string text2, DateTime deadline) { // Cache the text lengths to prevent multiple calls. @@ -558,16 +602,16 @@ protected List diff_bisect(string text1, string text2, return diffs; } - /** - * Given the location of the 'middle snake', split the diff in two parts - * and recurse. - * @param text1 Old string to be diffed. - * @param text2 New string to be diffed. - * @param x Index of split point in text1. - * @param y Index of split point in text2. - * @param deadline Time at which to bail if not yet complete. - * @return LinkedList of Diff objects. - */ + /// + /// Given the location of the 'middle snake', split the diff in two parts + /// and recurse. + /// + /// Old string to be diffed. + /// New string to be diffed. + /// Index of split point in text1. + /// Index of split point in text2. + /// Time at which to bail if not yet complete. + /// LinkedList of Diff objects. private List diff_bisectSplit(string text1, string text2, int x, int y, DateTime deadline) { string text1a = text1.Substring(0, x); @@ -583,15 +627,17 @@ private List diff_bisectSplit(string text1, string text2, return diffs; } - /** - * Split two texts into a list of strings. Reduce the texts to a string of - * hashes where each Unicode character represents one line. - * @param text1 First string. - * @param text2 Second string. - * @return Three element Object array, containing the encoded text1, the - * encoded text2 and the List of unique strings. The zeroth element - * of the List of unique strings is intentionally blank. - */ + /// + /// Split two texts into a list of strings. Reduce the texts to a string of + /// hashes where each Unicode character represents one line. + /// + /// First string. + /// Second string. + /// + /// Three element Object array, containing the encoded text1, the + /// encoded text2 and the List of unique strings. The zeroth element + /// of the List of unique strings is intentionally blank. + /// protected Object[] diff_linesToChars(string text1, string text2) { List lineArray = new List(); Dictionary lineHash = new Dictionary(); @@ -608,15 +654,15 @@ protected Object[] diff_linesToChars(string text1, string text2) { return new Object[] { chars1, chars2, lineArray }; } - /** - * Split a text into a list of strings. Reduce the texts to a string of - * hashes where each Unicode character represents one line. - * @param text String to encode. - * @param lineArray List of unique strings. - * @param lineHash Map of strings to indices. - * @param maxLines Maximum length of lineArray. - * @return Encoded string. - */ + /// + /// Split a text into a list of strings. Reduce the texts to a string of + /// hashes where each Unicode character represents one line. + /// + /// String to encode. + /// List of unique strings. + /// Map of strings to indices. + /// Maximum length of lineArray. + /// Encoded string. private string diff_linesToCharsMunge(string text, List lineArray, Dictionary lineHash, int maxLines) { int lineStart = 0; @@ -648,14 +694,14 @@ private string diff_linesToCharsMunge(string text, List lineArray, lineStart = lineEnd + 1; } return chars.ToString(); - } + } - /** - * Rehydrate the text in a diff from a string of line hashes to real lines - * of text. - * @param diffs List of Diff objects. - * @param lineArray List of unique strings. - */ + /// + /// Rehydrate the text in a diff from a string of line hashes to real lines + /// of text. + /// + /// List of Diff objects. + /// List of unique strings. protected void diff_charsToLines(ICollection diffs, IList lineArray) { StringBuilder text; @@ -668,12 +714,12 @@ protected void diff_charsToLines(ICollection diffs, } } - /** - * Determine the common prefix of two strings. - * @param text1 First string. - * @param text2 Second string. - * @return The number of characters common to the start of each string. - */ + /// + /// Determine the common prefix of two strings. + /// + /// First string. + /// Second string. + /// The number of characters common to the start of each string. public int diff_commonPrefix(string text1, string text2) { // Performance analysis: https://neil.fraser.name/news/2007/10/09/ int n = Math.Min(text1.Length, text2.Length); @@ -683,14 +729,14 @@ public int diff_commonPrefix(string text1, string text2) { } } return n; - } + } - /** - * Determine the common suffix of two strings. - * @param text1 First string. - * @param text2 Second string. - * @return The number of characters common to the end of each string. - */ + /// + /// Determine the common suffix of two strings. + /// + /// First string. + /// Second string. + /// The number of characters common to the end of each string. public int diff_commonSuffix(string text1, string text2) { // Performance analysis: https://neil.fraser.name/news/2007/10/09/ int text1_length = text1.Length; @@ -702,15 +748,17 @@ public int diff_commonSuffix(string text1, string text2) { } } return n; - } + } - /** - * Determine if the suffix of one string is the prefix of another. - * @param text1 First string. - * @param text2 Second string. - * @return The number of characters common to the end of the first - * string and the start of the second string. - */ + /// + /// Determine if the suffix of one string is the prefix of another. + /// + /// First string. + /// Second string. + /// + /// The number of characters common to the end of the first + /// string and the start of the second string. + /// protected int diff_commonOverlap(string text1, string text2) { // Cache the text lengths to prevent multiple calls. int text1_length = text1.Length; @@ -751,17 +799,18 @@ protected int diff_commonOverlap(string text1, string text2) { } } - /** - * Do the two texts share a Substring which is at least half the length of - * the longer text? - * This speedup can produce non-minimal diffs. - * @param text1 First string. - * @param text2 Second string. - * @return Five element String array, containing the prefix of text1, the - * suffix of text1, the prefix of text2, the suffix of text2 and the - * common middle. Or null if there was no match. - */ - + /// + /// Do the two texts share a Substring which is at least half the length of + /// the longer text? + /// This speedup can produce non-minimal diffs. + /// + /// First string. + /// Second string. + /// + /// Five element String array, containing the prefix of text1, the + /// suffix of text1, the prefix of text2, the suffix of text2 and the + /// common middle. Or null if there was no match. + /// protected string[] diff_halfMatch(string text1, string text2) { if (this.Diff_Timeout <= 0) { // Don't risk returning a non-optimal diff if we have unlimited time. @@ -800,16 +849,18 @@ protected string[] diff_halfMatch(string text1, string text2) { } } - /** - * Does a Substring of shorttext exist within longtext such that the - * Substring is at least half the length of longtext? - * @param longtext Longer string. - * @param shorttext Shorter string. - * @param i Start index of quarter length Substring within longtext. - * @return Five element string array, containing the prefix of longtext, the - * suffix of longtext, the prefix of shorttext, the suffix of shorttext - * and the common middle. Or null if there was no match. - */ + /// + /// Does a Substring of shorttext exist within longtext such that the + /// Substring is at least half the length of longtext? + /// + /// Longer string. + /// Shorter string. + /// Start index of quarter length Substring within longtext. + /// + /// Five element string array, containing the prefix of longtext, the + /// suffix of longtext, the prefix of shorttext, the suffix of shorttext + /// and the common middle. Or null if there was no match. + /// private string[] diff_halfMatchI(string longtext, string shorttext, int i) { // Start with a 1/4 length Substring at position i as a seed. string seed = longtext.Substring(i, longtext.Length / 4); @@ -838,13 +889,13 @@ private string[] diff_halfMatchI(string longtext, string shorttext, int i) { } else { return null; } - } + } - /** - * Reduce the number of edits by eliminating semantically trivial - * equalities. - * @param diffs List of Diff objects. - */ + /// + /// Reduce the number of edits by eliminating semantically trivial + /// equalities. + /// + /// List of Diff objects. public void diff_cleanupSemantic(List diffs) { bool changes = false; // Stack of indices where equalities are found. @@ -953,12 +1004,12 @@ public void diff_cleanupSemantic(List diffs) { } } - /** - * Look for single edits surrounded on both sides by equalities - * which can be shifted sideways to align the edit to a word boundary. - * e.g: The cat came. -> The cat came. - * @param diffs List of Diff objects. - */ + /// + /// Look for single edits surrounded on both sides by equalities + /// which can be shifted sideways to align the edit to a word boundary. + /// e.g: The cat came. -> The cat came. + /// + /// List of Diff objects. public void diff_cleanupSemanticLossless(List diffs) { int pointer = 1; // Intentionally ignore the first and last element (don't need checking). @@ -1022,16 +1073,16 @@ public void diff_cleanupSemanticLossless(List diffs) { } pointer++; } - } + } - /** - * Given two strings, compute a score representing whether the internal - * boundary falls on logical boundaries. - * Scores range from 6 (best) to 0 (worst). - * @param one First string. - * @param two Second string. - * @return The score. - */ + /// + /// Given two strings, compute a score representing whether the internal + /// boundary falls on logical boundaries. + /// Scores range from 6 (best) to 0 (worst). + /// + /// First string. + /// Second string. + /// The score. private int diff_cleanupSemanticScore(string one, string two) { if (one.Length == 0 || two.Length == 0) { // Edges are the best. @@ -1077,11 +1128,11 @@ private int diff_cleanupSemanticScore(string one, string two) { private Regex BLANKLINEEND = new Regex("\\n\\r?\\n\\Z"); private Regex BLANKLINESTART = new Regex("\\A\\r?\\n\\r?\\n"); - /** - * Reduce the number of edits by eliminating operationally trivial - * equalities. - * @param diffs List of Diff objects. - */ + /// + /// Reduce the number of edits by eliminating operationally trivial + /// equalities. + /// + /// List of Diff objects. public void diff_cleanupEfficiency(List diffs) { bool changes = false; // Stack of indices where equalities are found. @@ -1161,11 +1212,11 @@ public void diff_cleanupEfficiency(List diffs) { } } - /** - * Reorder and merge like edit sections. Merge equalities. - * Any edit section can move as long as it doesn't cross an equality. - * @param diffs List of Diff objects. - */ + /// + /// Reorder and merge like edit sections. Merge equalities. + /// Any edit section can move as long as it doesn't cross an equality. + /// + /// List of Diff objects. public void diff_cleanupMerge(List diffs) { // Add a dummy entry at the end. diffs.Add(new Diff(Operation.EQUAL, string.Empty)); @@ -1290,14 +1341,14 @@ public void diff_cleanupMerge(List diffs) { } } - /** - * loc is a location in text1, compute and return the equivalent location in - * text2. - * e.g. "The cat" vs "The big cat", 1->1, 5->8 - * @param diffs List of Diff objects. - * @param loc Location within text1. - * @return Location within text2. - */ + /// + /// loc is a location in text1, compute and return the equivalent location in + /// text2. + /// e.g. "The cat" vs "The big cat", 1->1, 5->8 + /// + /// List of Diff objects. + /// Location within text1. + /// Location within text2. public int diff_xIndex(List diffs, int loc) { int chars1 = 0; int chars2 = 0; @@ -1329,11 +1380,11 @@ public int diff_xIndex(List diffs, int loc) { return last_chars2 + (loc - last_chars1); } - /** - * Convert a Diff list into a pretty HTML report. - * @param diffs List of Diff objects. - * @return HTML representation. - */ + /// + /// Convert a Diff list into a pretty HTML report. + /// + /// List of Diff objects. + /// HTML representation. public string diff_prettyHtml(List diffs) { StringBuilder html = new StringBuilder(); foreach (Diff aDiff in diffs) { @@ -1356,11 +1407,11 @@ public string diff_prettyHtml(List diffs) { return html.ToString(); } - /** - * Compute and return the source text (all equalities and deletions). - * @param diffs List of Diff objects. - * @return Source text. - */ + /// + /// Compute and return the source text (all equalities and deletions). + /// + /// List of Diff objects. + /// Source text. public string diff_text1(List diffs) { StringBuilder text = new StringBuilder(); foreach (Diff aDiff in diffs) { @@ -1371,11 +1422,11 @@ public string diff_text1(List diffs) { return text.ToString(); } - /** - * Compute and return the destination text (all equalities and insertions). - * @param diffs List of Diff objects. - * @return Destination text. - */ + /// + /// Compute and return the destination text (all equalities and insertions). + /// + /// List of Diff objects. + /// Destination text. public string diff_text2(List diffs) { StringBuilder text = new StringBuilder(); foreach (Diff aDiff in diffs) { @@ -1386,12 +1437,12 @@ public string diff_text2(List diffs) { return text.ToString(); } - /** - * Compute the Levenshtein distance; the number of inserted, deleted or - * substituted characters. - * @param diffs List of Diff objects. - * @return Number of changes. - */ + /// + /// Compute the Levenshtein distance; the number of inserted, deleted or + /// substituted characters. + /// + /// List of Diff objects. + /// Number of changes. public int diff_levenshtein(List diffs) { int levenshtein = 0; int insertions = 0; @@ -1416,15 +1467,15 @@ public int diff_levenshtein(List diffs) { return levenshtein; } - /** - * Crush the diff into an encoded string which describes the operations - * required to transform text1 into text2. - * E.g. =3\t-2\t+ing -> Keep 3 chars, delete 2 chars, insert 'ing'. - * Operations are tab-separated. Inserted text is escaped using %xx - * notation. - * @param diffs Array of Diff objects. - * @return Delta text. - */ + /// + /// Crush the diff into an encoded string which describes the operations + /// required to transform text1 into text2. + /// E.g. =3\t-2\t+ing -> Keep 3 chars, delete 2 chars, insert 'ing'. + /// Operations are tab-separated. Inserted text is escaped using %xx + /// notation. + /// + /// Array of Diff objects. + /// Delta text. public string diff_toDelta(List diffs) { StringBuilder text = new StringBuilder(); foreach (Diff aDiff in diffs) { @@ -1448,14 +1499,14 @@ public string diff_toDelta(List diffs) { return delta; } - /** - * Given the original text1, and an encoded string which describes the - * operations required to transform text1 into text2, compute the full diff. - * @param text1 Source string for the diff. - * @param delta Delta text. - * @return Array of Diff objects or null if invalid. - * @throws ArgumentException If invalid input. - */ + /// + /// Given the original text1, and an encoded string which describes the + /// operations required to transform text1 into text2, compute the full diff. + /// + /// Source string for the diff. + /// Delta text. + /// Array of Diff objects or null if invalid. + /// If invalid input. public List diff_fromDelta(string text1, string delta) { List diffs = new List(); int pointer = 0; // Cursor in text1 @@ -1531,14 +1582,14 @@ public List diff_fromDelta(string text1, string delta) { // MATCH FUNCTIONS - /** - * Locate the best instance of 'pattern' in 'text' near 'loc'. - * Returns -1 if no match found. - * @param text The text to search. - * @param pattern The pattern to search for. - * @param loc The location to search around. - * @return Best match index or -1. - */ + /// + /// Locate the best instance of 'pattern' in 'text' near 'loc'. + /// Returns -1 if no match found. + /// + /// The text to search. + /// The pattern to search for. + /// The location to search around. + /// Best match index or -1. public int match_main(string text, string pattern, int loc) { // Check for null inputs not needed since null can't be passed in C#. @@ -1559,14 +1610,14 @@ public int match_main(string text, string pattern, int loc) { } } - /** - * Locate the best instance of 'pattern' in 'text' near 'loc' using the - * Bitap algorithm. Returns -1 if no match found. - * @param text The text to search. - * @param pattern The pattern to search for. - * @param loc The location to search around. - * @return Best match index or -1. - */ + /// + /// Locate the best instance of 'pattern' in 'text' near 'loc' using the + /// Bitap algorithm. Returns -1 if no match found. + /// + /// The text to search. + /// The pattern to search for. + /// The location to search around. + /// Best match index or -1. protected int match_bitap(string text, string pattern, int loc) { // assert (Match_MaxBits == 0 || pattern.Length <= Match_MaxBits) // : "Pattern too long for this application."; @@ -1664,14 +1715,14 @@ protected int match_bitap(string text, string pattern, int loc) { return best_loc; } - /** - * Compute and return the score for a match with e errors and x location. - * @param e Number of errors in match. - * @param x Location of match. - * @param loc Expected location of match. - * @param pattern Pattern being sought. - * @return Overall score for match (0.0 = good, 1.0 = bad). - */ + /// + /// Compute and return the score for a match with e errors and x location. + /// + /// Number of errors in match. + /// Location of match. + /// Expected location of match. + /// Pattern being sought. + /// Overall score for match (0.0 = good, 1.0 = bad). private double match_bitapScore(int e, int x, int loc, string pattern) { float accuracy = (float)e / pattern.Length; int proximity = Math.Abs(loc - x); @@ -1682,11 +1733,11 @@ private double match_bitapScore(int e, int x, int loc, string pattern) { return accuracy + (proximity / (float) Match_Distance); } - /** - * Initialise the alphabet for the Bitap algorithm. - * @param pattern The text to encode. - * @return Hash of character locations. - */ + /// + /// Initialise the alphabet for the Bitap algorithm. + /// + /// The text to encode. + /// Hash of character locations. protected Dictionary match_alphabet(string pattern) { Dictionary s = new Dictionary(); char[] char_pattern = pattern.ToCharArray(); @@ -1708,12 +1759,12 @@ protected Dictionary match_alphabet(string pattern) { // PATCH FUNCTIONS - /** - * Increase the context until it is unique, - * but don't let the pattern expand beyond Match_MaxBits. - * @param patch The patch to grow. - * @param text Source text. - */ + /// + /// Increase the context until it is unique, + /// but don't let the pattern expand beyond Match_MaxBits. + /// + /// The patch to grow. + /// Source text. protected void patch_addContext(Patch patch, string text) { if (text.Length == 0) { return; @@ -1754,13 +1805,13 @@ protected void patch_addContext(Patch patch, string text) { patch.length2 += prefix.Length + suffix.Length; } - /** - * Compute a list of patches to turn text1 into text2. - * A set of diffs will be computed. - * @param text1 Old text. - * @param text2 New text. - * @return List of Patch objects. - */ + /// + /// Compute a list of patches to turn text1 into text2. + /// A set of diffs will be computed. + /// + /// Old text. + /// New text. + /// List of Patch objects. public List patch_make(string text1, string text2) { // Check for null inputs not needed since null can't be passed in C#. // No diffs provided, compute our own. @@ -1772,12 +1823,12 @@ public List patch_make(string text1, string text2) { return patch_make(text1, diffs); } - /** - * Compute a list of patches to turn text1 into text2. - * text1 will be derived from the provided diffs. - * @param diffs Array of Diff objects for text1 to text2. - * @return List of Patch objects. - */ + /// + /// Compute a list of patches to turn text1 into text2. + /// text1 will be derived from the provided diffs. + /// + /// Array of Diff objects for text1 to text2. + /// List of Patch objects. public List patch_make(List diffs) { // Check for null inputs not needed since null can't be passed in C#. // No origin string provided, compute our own. @@ -1785,27 +1836,27 @@ public List patch_make(List diffs) { return patch_make(text1, diffs); } - /** - * Compute a list of patches to turn text1 into text2. - * text2 is ignored, diffs are the delta between text1 and text2. - * @param text1 Old text - * @param text2 Ignored. - * @param diffs Array of Diff objects for text1 to text2. - * @return List of Patch objects. - * @deprecated Prefer patch_make(string text1, List diffs). - */ + /// + /// Compute a list of patches to turn text1 into text2. + /// text2 is ignored, diffs are the delta between text1 and text2. + /// + /// Old text + /// Ignored. + /// Array of Diff objects for text1 to text2. + /// List of Patch objects. + [Obsolete("Prefer patch_make(string text1, List diffs).")] public List patch_make(string text1, string text2, List diffs) { return patch_make(text1, diffs); } - /** - * Compute a list of patches to turn text1 into text2. - * text2 is not provided, diffs are the delta between text1 and text2. - * @param text1 Old text. - * @param diffs Array of Diff objects for text1 to text2. - * @return List of Patch objects. - */ + /// + /// Compute a list of patches to turn text1 into text2. + /// text2 is not provided, diffs are the delta between text1 and text2. + /// + /// Old text. + /// Array of Diff objects for text1 to text2. + /// List of Patch objects. public List patch_make(string text1, List diffs) { // Check for null inputs not needed since null can't be passed in C#. List patches = new List(); @@ -1882,11 +1933,11 @@ public List patch_make(string text1, List diffs) { return patches; } - /** - * Given an array of patches, return another array that is identical. - * @param patches Array of Patch objects. - * @return Array of Patch objects. - */ + /// + /// Given an array of patches, return another array that is identical. + /// + /// Array of Patch objects. + /// Array of Patch objects. public List patch_deepCopy(List patches) { List patchesCopy = new List(); foreach (Patch aPatch in patches) { @@ -1904,14 +1955,13 @@ public List patch_deepCopy(List patches) { return patchesCopy; } - /** - * Merge a set of patches onto the text. Return a patched text, as well - * as an array of true/false values indicating which patches were applied. - * @param patches Array of Patch objects - * @param text Old text. - * @return Two element Object array, containing the new text and an array of - * bool values. - */ + /// + /// Merge a set of patches onto the text. Return a patched text, as well + /// as an array of true/false values indicating which patches were applied. + /// + /// Array of Patch objects. + /// Old text. + /// Two element Object array, containing the new text and an array of bool values. public Object[] patch_apply(List patches, string text) { if (patches.Count == 0) { return new Object[] { text, new bool[0] }; @@ -2013,12 +2063,12 @@ public Object[] patch_apply(List patches, string text) { return new Object[] { text, results }; } - /** - * Add some padding on text start and end so that edges can match something. - * Intended to be called only from within patch_apply. - * @param patches Array of Patch objects. - * @return The padding string added to each side. - */ + /// + /// Add some padding on text start and end so that edges can match something. + /// Intended to be called only from within patch_apply. + /// + /// Array of Patch objects. + /// The padding string added to each side. public string patch_addPadding(List patches) { short paddingLength = this.Patch_Margin; string nullPadding = string.Empty; @@ -2074,12 +2124,12 @@ public string patch_addPadding(List patches) { return nullPadding; } - /** - * Look through the patches and break up any which are longer than the - * maximum limit of the match algorithm. - * Intended to be called only from within patch_apply. - * @param patches List of Patch objects. - */ + /// + /// Look through the patches and break up any which are longer than the + /// maximum limit of the match algorithm. + /// Intended to be called only from within patch_apply. + /// + /// List of Patch objects. public void patch_splitMax(List patches) { short patch_size = this.Match_MaxBits; for (int x = 0; x < patches.Count; x++) { @@ -2175,11 +2225,11 @@ public void patch_splitMax(List patches) { } } - /** - * Take a list of patches and return a textual representation. - * @param patches List of Patch objects. - * @return Text representation of patches. - */ + /// + /// Take a list of patches and return a textual representation. + /// + /// List of Patch objects. + /// Text representation of patches. public string patch_toText(List patches) { StringBuilder text = new StringBuilder(); foreach (Patch aPatch in patches) { @@ -2188,13 +2238,13 @@ public string patch_toText(List patches) { return text.ToString(); } - /** - * Parse a textual representation of patches and return a List of Patch - * objects. - * @param textline Text representation of patches. - * @return List of Patch objects. - * @throws ArgumentException If invalid input. - */ + /// + /// Parse a textual representation of patches and return a List of Patch + /// objects. + /// + /// Text representation of patches. + /// List of Patch objects. + /// If invalid input. public List patch_fromText(string textline) { List patches = new List(); if (textline.Length == 0) { @@ -2273,13 +2323,12 @@ Regex patchHeader return patches; } - /** - * Encodes a string with URI-style % escaping. - * Compatible with JavaScript's encodeURI function. - * - * @param str The string to encode. - * @return The encoded string. - */ + /// + /// Encodes a string with URI-style % escaping. + /// Compatible with JavaScript's encodeURI function. + /// + /// The string to encode. + /// The encoded string. public static string encodeURI(string str) { // C# is overzealous in the replacements. Walk back on a few. return new StringBuilder(HttpUtility.UrlEncode(str))