INTERFACE PZCandidate;

IMPORT Rd, Wr;
IMPORT PZSymbolChain, PZSegment;

TYPE
  T = RECORD 
      int:  ARRAY[0..1] OF PZSegment.T;
      mismatch:  LONGREAL;  (* Some integral of the distance biased. *)
      length: LONGREAL;     (* Total length of the two matched segments. *)
      matched: LONGREAL;    (* Length effectively matched *)
    END;              
      (*         
        A tentative matching between two curves. *)

  List = ARRAY OF T;
  
  ReadData = RECORD
      cmt: TEXT;
      lambda: LONGREAL;
      c: REF List
    END;
    

PROCEDURE Write(
    wr :Wr.T; 
    cmt: TEXT;
    READONLY c: List;
    lambda: LONGREAL;
  );
  (*
    Writes the list of candidates "c" and the parameter "lambda"
    to the writer "wr". *)

PROCEDURE Read(rd :Rd.T): ReadData;
  (*
    Reads from "rd" a list of candidates that was written by "Write". *)
    
PROCEDURE GetCurves(READONLY cand: List): REF ARRAY OF BOOLEAN;
  (*
    Returns a vector "seen" such that "seen[k]" is TRUE
    iff curve "k" occurs in some candidate of "cand". *)

TYPE 
  ChainPair = ARRAY [0..1] OF PZSymbolChain.ReadData;

PROCEDURE Print(
    wr: Wr.T;
    prefix: TEXT;
    READONLY cand: T; 
    READONLY chain: ChainPair;
    reverse: BOOLEAN := TRUE;
  );
  (*
    Prints the candidate "cand" to "wr", in a readable format.
    If the "chain"s are not NIL, also prints the corresponding
    segment of each chain. 
    
    Normally the second chain is reversed and complemented;
    specify "reverse = FALSE" to print it out as it is. *)

TYPE CompareProc = PROCEDURE(READONLY a, b: T): BOOLEAN;
  (* 
    A procedure that tells whether "a" must come before "b". *)

PROCEDURE Sort(VAR c: List; before: CompareProc);
  (*
    Sorts the list "c" according to the given comparison procedure. *)
    
PROCEDURE LexBetter(READONLY a, b: T): BOOLEAN;
  (*
    Compares by curve pair, breaking ties by "mismatch" and other criteria. *)

PROCEDURE AbsBetter(READONLY a, b: T): BOOLEAN;
  (*
    Compares by "mismatch", breaking ties by other criteria. *)

PROCEDURE Prune(
    VAR c: List;
    VAR nCands: CARDINAL;
    candsPerCurve: CARDINAL;
    candsPerPair: CARDINAL;
  );
  (*
    Removes duplicates, and excess
    candidates for each curve or curve pair. 
    Assumes that the list "c" has been sorted by curve pair FIRST,
    then by decreasing quality of match (the "mismatch" field, currently), 
    as per "LexBetter". *)

PROCEDURE MergeOverlaps(
    VAR c: List;
    VAR nCands: CARDINAL;
    READONLY cvc: ARRAY OF PZSymbolChain.ReadData;
    indexTol: LONGREAL;    (* Tolerance for alignment tests (samples). *)
  );
  (*
    Joins overlapping candidates. Assumes candidates are 
    sorted by "LexBetter". *)
    
PROCEDURE Overlap(READONLY a, b: T; m0, m1: CARDINAL; indexTol: LONGREAL): BOOLEAN; 
  (*
    TRUE if the candidates "a" and "b" belong to the same 
    curve pair, have similar alignments (up to the specified "indexTol"), 
    and overlap significantly (but at only one end) in both curves. 
    The arguments "m0" and "m1"  should be the number of samples
    in each curve.
  *)   

END PZCandidate.