Test submitted by email by Jack Woollen

[edwardhartnett]

@jack-woollen emailed me some test code. Not sure why he didn't just make a PR.

I put the test code in, but it doesn't work. See code comments for discussion.

[edwardhartnett]

@jack-woollen or @jbathegit can you take a look at this PR and try to answer some of the questions?

[jbathegit]

Sorry, I'm going to have to defer to Jack to answer the remaining questions. I've never really understood what newwin does, or else I would have already tried to write a test for it.

[edwardhartnett]

@jack-woollen why was this closed?

When we have code in the library that only one person understands how to use, that's a big problem. What is the deal with this windowing code that makes it so difficult?

Can this code be removed from the library if it cannot be tested or documented in such a way that other maintainers can understand and use it?

What good is code that no one can figure out how to use? Surely our users cannot figure this out, if @jbathegit cannot...

[jack-woollen]

@edwardhartnett I thought we agreed the ufbrw test code tested all the windowing codes. Are you talking about testing or documentation? I can write some more docs if you want.

[edwardhartnett]

OK, I appologize. Somehow I missed the fact that the windowing code is now being tested.

@jack-woollen the documentation of the windowing code can be much improved. There are a bunch of questions that I ask about the code in this PR. Can you answer those questions and we can see if we can improve the documentation so that both @jbathegit and I have a better understanding of the windowing code?

[jack-woollen]

Yup, will do. Thanks for the explanation.

[jack-woollen]

Here is a compilation of the docblocks for the windowing routines. It would help to understand what isn't clear. Thanks!

conwin.f

C> @file C> @brief Search consecutive subset buffer segments C> for an element identified in the user string as a conditional node. C> @author Woollen @date 1994-01-06 C> This subroutine searches consecutive subset buffer segments for an C> element identified in the user string as a conditional node. A conditional C> node is an element which must meet a condition in order to be read C> from or written to a data subset. If a conditional element is C> found and it conforms to the condition, then the internal subset C> buffer indices of the "window" (see below remarks) are returned to C> the caller for processing. C> C> The four conditions which can be exercised are: C> - '<' - less than C> - '>' - greater than C> - '=' - equal C> - '!' - not equal C> C> Each condition in a string is applied to one element, and all C> conditions are 'and'ed to evaluate an outcome. For example, if the C> condition string is: "POB<500 TOB>30 TQM<4" then the only levels of C> data read or written are those with pressure lt 500 mb, temperature C> gt 30 deg, and temperature quality mark < 4. C> C> See getwin() for an explanation of "windows" within the context of a C> BUFR data subset. C> C> Function conwin() works with function invcon() to identify subset C> buffer segments which conform to the set of conditions. C> C> @param[in] LUN integer I/O stream index into internal memory arrays. C> @param[out] INC1 integer subset buffer start index C> @param[inout] INC2 integer subset buffer ending index C> C> @author Woollen @date 1994-01-06

getwin.f

C> @file C> @brief Look for a window containing a specified node within C> the internal jump/link table. C> @author Woollen @date 1994-01-06 C> Given a node index within the internal jump/link table, this C> subroutine looks within the current subset buffer for a "window" C> (see below remarks) which contains this node. If found, it returns C> the starting and ending indices of this window within the current C> subset buffer. For example, if the node is found within the subset C> but is not part of a delayed replication sequence, then the returned C> indices define the start and end of the entire subset buffer. C> Otherwise, the returned indices define the start and end of the next C> available delayed replication sequence iteration which contains the C> node. If no further iterations of the sequence can be found, then C> the starting index is returned with a value of zero. C> C> @note C> This is one of a number of subroutines which operate on "windows" C> (i.e. contiguous portions) of the internal subset buffer. The C> subset buffer is an array of values arranged according to the C> overall template definition for a subset. A window can be any C> contiguous portion of the subset buffer up to and including the C> entire subset buffer itself. For the purposes of these "window C> operator" subroutines, a window essentially consists of all of the C> elements within a particular delayed replication group, since such C> groups effectively define the dimensions within a bufr subset for C> the BUFR archive library subroutines such as ufbint(), ufbin3(), etc. C> which read/write individual data values. A bufr subset with no C> delayed replication groups is considered to have only one C> dimension, and therefore only one "window" which spans the entire C> subset. On the other hand, each delayed replication sequence C> within a bufr subset consists of some number of "windows", which C> are a de-facto second dimension of the subset and where the number C> of windows is the delayed descriptor replication factor (i.e. the C> number of iterations) of the sequence. If nested delayed C> replication is used, then there may be three or more dimensions C> within the subset. C> C> @param[in] NODE - integer: jump/link table index of mnemonic to look for. C> @param[in] LUN - integer: i/o stream index into internal memory arrays. C> @param[out] IWIN - integer: starting index of the current window iteration which contains node C> - 0 = not found or no more iterations available. C> @param[out] JWIN - integer: ending index of the current window iteration which contains node. C> C> @author Woollen @date 1994-01-06

invwin.f

C> @file C> @brief Search for a specified node within a specified portion C> of the current data subset. C> C> @author Woollen @date 1994-01-06 C> This function looks for a specified node within the portion C> of the current subset buffer bounded by the indices inv1 and inv2. C> It is similar to library function invtag(), except that C> invtag() searches based on the mnemonic corresponding to the node. C> C> @param[in] NODE - integer: jump/link table index to look for C> @param[in] LUN - integer: file ID C> @param[in] INV1 - integer: starting index of the portion of the subset buffer in which to look C> @param[in] INV2 - integer: ending index of the portion of the subset buffer in which to look C> C> @return - integer: location index of node within specified portion of subset buffer C> - 0 not found C> C> @author Woollen @date 1994-01-06

newwin.f

C> @file C> @brief Computes the ending index of the window. C> C> @author J. Woollen @date 1994-01-06 C> Given an index within the internal jump/link table which C> points to the start of an "rpc" window (which is the iteration of an 8-bit C> or 16-bit delayed replication sequence), this subroutine computes C> the ending index of the window. Alternatively, if the given index C> points to the start of a "sub" window (which is the first node of a C> subset), then the subroutine returns the index of the last node. C> C> @note See the docblock in bufr archive library subroutine getwin() for an C> explanation of "windows" within the context of a bufr data subset. C> C> @param[in] LUN - integer: i/o stream index into internal memory arrays. C> @param[in] IWIN - integer: starting index of window iteration. C> @param[out] JWIN - integer: ending index of window iteration. C> C> @author J. Woollen @date 1994-01-06

nvnwin.f

C> @file C> @brief Search for all occurrences of a specified node within a C> specified portion of the current data subset. C> C> @author Woollen @date 1994-01-06 C> This function looks for and returns all occurrences of a C> specified node within the portion of the current subset buffer C> bounded by the indices inv1 and inv2. The resulting list is a C> stack of "event" indices for the requested node. C> C> @param[in] NODE - integer: jump/link table index to look for. C> @param[in] LUN - integer: i/o stream index into internal memory arrays. C> @param[in] INV1 - integer: starting index of the portion of the subset buffer in which to look. C> @param[in] INV2 - integer: ending index of the portion of the subset buffer in which to look. C> @param[out] INVN - integer: array of stack "event" indices for node. C> @param[in] NMAX - integer: dimensioned size of invn; used by the function to ensure C> that it does not overflow the invn array. C> C> @return number of indices within invn. C> C> @author Woollen @date 1994-01-06

nxtwin.f

C> @file C> @brief Computes the start and end indices of the next window. C> C> @author J. Woollen @date 1994-01-06 C> Given indices within the internal jump/link table which C> point to the start and end of an "rpc" window (which is an iteration of C> an 8-bit or 16-bit delayed replication sequence), this subroutine C> computes the start and end indices of the next window. C> C> @note See getwin() for an explanation of "windows" within the C> context of a bufr data subset. C> C> @param[in] LUN - integer: i/o stream index into internal memory arrays. C> @param[inout] IWIN - integer: C> - on input, contains starting index of current window iteration. C> - on output, contains starting index of next window iteration. C> @param[inout] JWIN - integer: C> - on input, contains ending index of current window iteration. C> - on output, contains ending index of next window iteration. C> C> @author J. Woollen @date 1994-01-06