Re: [PATCH v5 12/13] xdiff: use enum macros NONE(0), SOME(1), TOO_MANY(2) in xprepare.c

On Wed, Sep 24, 2025 at 9:18 AM Phillip Wood <phillip.wood123@gmail.com> wrote:

I'm really struggling with how to write this commit message. I would very much appreciate suggestions. Here is what I have so far: --- commit message start --- xdiff: use enum macros NONE(0), SOME(1), TOO_MANY(2) in xprepare.c

The local variables dis1 and dis2 describe how a line should be treated based on how many lines, in the other file, match this line. NONE means the other file does not have any matches to this line. SOME means that there are more than 0 matches, but less than some heuristic threshold. TOO_MANY is when there are more matches than that heuristic threshold.

Note: When need_min is true, matches[i] is always set to SOME when the
number of matches is greater than 0.

The names dis1 and dis2 don't convey what they mean, so let's rename them to matches1 and matches2.

Define macros NONE(0), SOME(1), TOO_MANY(2) as the enum values for matches1 and matches2. These states will influence whether changed[i] is set to 1 or kept as 0.

The variables r, rdis0, rpdis0, rdis1, rpdis1 in xdl_clean_mmatch() have not been renamed because I don't understand their purpose. --- commit message end ---

I'll explain the parts of the code that are relevant to the commit message with an example. The following snippet goes through every line (matches1[i]) of file1 to determine what matches1[i] should be by looking at the number of times that line shows up in file2.

    if ((mlim = xdl_bogosqrt(xdf1->nrec)) > XDL_MAX_EQLIMIT)
        mlim = XDL_MAX_EQLIMIT;
    for (i = xdf1->dstart, recs = &xdf1->recs[xdf1->dstart]; i <=
xdf1->dend; i++, recs++) {
        rcrec = cf->rcrecs[recs->ha];
        nm = rcrec ? rcrec->len2 : 0;
        matches1[i] = (nm == 0) ? NONE: (nm >= mlim && !need_min) ?
TOO_MANY: SOME;
    }

The lines:
    rcrec = cf->rcrecs[recs->ha];
    nm = rcrec ? rcrec->len2 : 0;
gets the number of matches from file2 (i.e. rcrec->len2), and then this line:
    matches1[i] = (nm == 0) ? NONE: (nm >= mlim && !need_min) ? TOO_MANY: SOME;
Is the logic to set matches1[i] (the line in question of file1) to
NONE, SOME, or TOO_MANY.
mlim seems to be some heuristic threshold based on the XDL_MAX_EQLIMIT
constant which is set to 1024.