Christmas Bird Count history report system

The argument pairList is a list of tuples (y, c) such that y is a year number and c is the number of repetitions of that year number.

The purpose of this function is to find and remove the first date group from pairList and return the equivalent textual form. There are three kinds of date groups:

# - - -   p e e l G r o u p

def peelGroup ( pairList ):
    '''Remove one sequence, repeat group, or single value from pairList.

      [ pairList is a non-empty sequence of (value, count) tuples such
        that the values are ints in ascending order and the
        count is an int >= 1 ->
          if pairList[0][1] > 1 ->
            pairList  :=  pairList with its first pair removed
            return str(pairList[0][0]) + '(' + str(pairList[0][1] + ')'
          else if pairList starts with a sequence of two or more
          pairs such that the values go up by 1 each time and
          the counts are never greater than 1 ->
            pairList  :=  pairList with those pairs removed
            return str(first value) + '-' + str(last value)
          else ->
            pairList  :=  pairList with the first pair removed
            return str(first value) ]
    '''

First we eliminate the multiply-counted-year case.

    #-- 1
    # [ first  :=  first value from pairList
    #   firstCount  :=  first count from pairList
    #   pairList  :=  pairList with its first pair deleted ]
    first, firstCount = pairList.pop(0)

    #-- 2
    if firstCount > 1:
        return "%d(%d)" % (first, firstCount)

Next we check for a sequence of singly-counted years.

    #-- 3
    # [ if pairList starts with a pair (first+1, 1) ->
    #       pairList  :=  pairList with all pairs removed that
    #           form a sequence (first+1, 1), (first+2, 1), ...
    #       return str(first) + '-' + str(last value) ]
    if ( ( len(pairList) > 0 ) and
         ( first+1 == pairList[0][0] ) and
         ( 1 == pairList[0][1] ) ):
        last = first
        while ( ( len(pairList) > 0) and
                ( last+1 == pairList[0][0] ) and
                ( 1 == pairList[0][1] ) ):
            last, lastCount = pairList.pop(0)
        return '%d%s%d' % (first, NDASH, last)

If all else fails, we have a singleton.

    #-- 4
    return str(first)