An Example Package
 

 


next up previous contents
Next: Maintenance Utilities Up: No Title Previous: Naming Conventions

An Example Package

 

This chapter contains an example package intended to clarify the conventions. This is a package called ``rng'' that manipulates a data structure describing an integer range, i.e., sets of the form for integers and .

This small, contrived example contains 4 files: two header files, rng.h and rngInt.h; and two source files, rngUtil.c, and rngIntUtil.c.

The External Header File rng.h

/**CHeaderFile*****************************************************************
  FileName    [rng.h]
  PackageName [rng]
  Synopsis    [This package deals with functions that are used to manipulate
  the range (Rng_Range_t) data structure.]
 
  Description [ The basic data structure in the range package is an
  integer range. The range is designated as {L,U}, where L is the lower limit of 
  the range, and U is the upper limit of the range, and  
  includes all integers x, L =< x =< U).]
  SeeAlso     [tbl]
  Author      [Gitanjali Swamy]

  Copyright   [Copyright (c) 1994-1996 The Regents of the Univ. of California.
  All rights reserved.]
  Revision    [$Id: node5.html,v 1.1.1.1 2001/04/26 21:30:15 vis Exp $]

******************************************************************************/
#ifndef _RNG
#define _RNG

/*---------------------------------------------------------------------------*/
/* Constant declarations                                                     */
/*---------------------------------------------------------------------------*/
int RNG_MIN = 0;
int RNG_MAX = 5000;

/*---------------------------------------------------------------------------*/
/* Type declarations                                                         */
/*---------------------------------------------------------------------------*/
typedef struct RngRangeStruct Rng_Range_t;

/*---------------------------------------------------------------------------*/
/* Variable declarations                                                     */
/*---------------------------------------------------------------------------*/
extern int Rng_NumRanges;

/*---------------------------------------------------------------------------*/
/* Macro declarations                                                        */
/*---------------------------------------------------------------------------*/

/**Macro**********************************************************************
  Synopsis     [Return the beginning of the range.]
  Description  [Given a range {L,U}, this returns the beginning value
                L of the range.]
  SideEffects []
  SeeAlso      [Rng_RangeReadEnd]
******************************************************************************/
#define Rng_RangeReadBegin(range)\
(((range->begin) >= RNG_MIN)? (range->begin): RNG_MIN)

/**Macro**********************************************************************
  Synopsis     [return the end of the range.]
  Description  [Given a range {L,U}, this returns the ending value
                U of the range.]
  SideEffects []
  SeeAlso      [Rng_RangeReadBegin]
******************************************************************************/
#define Rng_RangeReadEnd(range)\
(((range->begin) =< RNG_MAX)? (range->begin): RNG_MAX)

/**Macro**********************************************************************
  Synopsis     [Set the beginning of the range.]
  Description  [Given a range and a value L, this sets the beginning value
                L of the range.]
  SideEffects  [There original beginning value of the range is lost.]
  SeeAlso      [Rng_RangeSetEnd]
******************************************************************************/
#define Rng_RangeSetBegin(range,val)\
((val >= RNG_MIN)? ((range->begin)=val): (range->begin =RNG_MIN))

/**Macro**********************************************************************
  Synopsis     [Set the end of the range]
  Description  [Given a range and a value L, this sets the end value
   L of the range.]
  SideEffects  [There original ending value of the range is lost.]
  SeeAlso      [Rng_RangeSetBegin]
******************************************************************************/
#define Rng_RangeSetEnd(range,val)\
((val <= RNG_MAX)? ((range->end)=val): (range->end =RNG_MAX))

/**AutomaticStart*************************************************************/
/**AutomaticEnd***************************************************************/
#endif /* _RNG */

The Internal Header File rngInt.h

/**CHeaderFile*****************************************************************
  FileName    [rngInt.h]
  PackageName [rng]
  Synopsis    [This package deals with functions that are used to manipulate
  the range (Rng_Range_t) data structure.]
 
  Description [ The basic data structure in the range package 
  is an integer range (range= {L,U}, where L is the lower limit of 
  the range, and U is the upper limit of the range. The range {L,U} 
  includes all integers x, L =< x =< U).]
  SeeAlso     [tbl.h rng.h]
  Author      [Gitanjali Swamy]
  Copyright   [Copyright (c) 1994-1996 The Regents of the Univ. of California.
  All rights reserved.]
  Revision    [$Id: node5.html,v 1.1.1.1 2001/04/26 21:30:15 vis Exp $]
******************************************************************************/
#ifndef _RNGINT
#define _RNGINT

#include "rng.h"

/*---------------------------------------------------------------------------*/
/* Stucture declarations                                                     */
/*---------------------------------------------------------------------------*/

/**Struct*************************************************************
  Synopsis      [ This struct represents a range.]
  Description   [ This struct represents a range and has 2 fields;
                  the beginning and the end.]
  SeeAlso       [ Rng_RangeAlloc Rng_RangeFree ]
**********************************************************************/
struct RngRangeStruct {
    int begin; /* The beginning of the range */
    int end;   /* The end of the range */
};

/*---------------------------------------------------------------------------*/
/* Macro declarations                                                        */
/*---------------------------------------------------------------------------*/

/**Macro***********************************************************************
  Synopsis     [Get the maximum of two number]
  Description  [Given two integers u1 and u2, this will return the
  maximum of the two.]
  SideEffects  []
  SeeAlso      [RngRangesMin]
******************************************************************************/
#define RngRangesMax(u1, u2)\
(u1 > u2) ? u1 : u2

/**Macro***********************************************************************
  Synopsis     [Get the minimum of two number]
  Description  [Given two integers u1 and u2, this will return the
  minimum of the two.]
  SideEffects  []
  SeeAlso      [RngRangesMax]
******************************************************************************/
#define RngRangesMin(u1, u2)\
(u1 < u2) ? u1 : u2

/**AutomaticStart*************************************************************/
/**AutomaticEnd***************************************************************/
#endif /* _RNGINT */

rngUtil.c

/**CFile***********************************************************************
  FileName    [rngRangeUtil.c]
  PackageName [rng]
  Synopsis    [This file deals with utilities that are exported to
   handle the range Rng_Range_t data structure.]

  Description [ This file contains memory management utilities, and 
  functions for oring together two ranges. The range data structure or
  Rng_Range_t has two fields; range->begin (the beginning of the
  range) and range->end (the end of the range). These are accessed using
  macros define in rng.h.]

  SeeAlso     [rng.h rngInt.h rngUtilInt.c]
  Author      [Gitanjali Swamy]
  Copyright   [Copyright (c) 1994-1996 The Regents of the Univ. of California.
  All rights reserved.]
******************************************************************************/
#include "rngInt.h"

static char rcsid[] = "$Id: node5.html,v 1.1.1.1 2001/04/26 21:30:15 vis Exp $";
USE(rcsid);

/**AutomaticStart*************************************************************/
/**AutomaticEnd***************************************************************/

/*---------------------------------------------------------------------------*/
/* Variable declarations                                                     */
/*---------------------------------------------------------------------------*/
int Rng_NumRanges;

/*---------------------------------------------------------------------------*/
/* Definition of exported functions                                          */
/*---------------------------------------------------------------------------*/

/**Function********************************************************************
  Synopsis    [Allocates memory for a Rng_Range_t.]
  Description [This functions takes no inputs, and when called
  allocates space for and returns a new Rng_Range_t.]
  SideEffects []
  SeeAlso     [Rng_RangeFree]
******************************************************************************/
Rng_Range_t*
Rng_RangeAlloc()
{
  Rng_Range_t *range;

  range = ALLOC(Rng_Range_t,1);
  return range;
}

/**Function********************************************************************
  Synopsis    [Free memory associated with a Rng_Range_t.]
  Description [This function takes a Rng_Range_t* as input, and free
  the memory used by it.]
  SideEffects [Rng_Range_t is no longer valid.]
  SeeAlso     [Rng_RangeAlloc]
******************************************************************************/
void
Rng_RangeFree(Rng_Range_t *range)
{
  FREE(range);
}

/**Function********************************************************************
  Synopsis    [OR two ranges.]
  Description [Given two ranges, this function unions together the two,
  and returns the result. If the two ranges do not overlap it returns
  with an error flag.]
  SideEffects []
******************************************************************************/
Rng_Range_t *
Rng_RangeOrWithRange(Rng_Range_t* range1, Rng_Range_t* range2)
{
   Rng_Range_t* newrange;

  if ( !(RangeOverlap(range1,range2)) || !(RngRangeIsOK(range1)) || 
       !(RngRangeIsOK(range2)) ) {
     error_flag();
     return NIL(Rng_Range_t);
  } else {
    newrange = Rng_RangeAlloc();
    Rng_RangeSetBegin( newrange, RngRangesMin(Rng_RangeReadBegin(range1),
                       Rng_RangeReadBegin(range2)) );
    Rng_RangeSetEnd( newrange, RngRangesMax(Rng_RangeReadEnd(range1), 
                       Rng_RangeReadEnd(range2)));
  }
 return newrange;
}

/*---------------------------------------------------------------------------*/
/* Definition of static functions                                            */
/*---------------------------------------------------------------------------*/

/**Function********************************************************************
  Synopsis    [Check if ranges overlap.]
  Description [Given two ranges of the type Rng_Range_t*, this
  function returns TRUE if they overlap, and FALSE if they do not.]
  SideEffects []
  SeeAlso     [Rng_RangeOrWithRange]
******************************************************************************/
static boolean 
RangeOverlap(Rng_Range_t *range1, Rng_Range_t *range2)
{
 if ( (Rng_RangeReadBegin(range1) > (Rng_RangeReadEnd(range2) - 1)) ||
      (Rng_RangeReadBegin(range2) > (Rng_RangeReadEnd(range1) - 1)) ) {
   return 0;
 } else {
   return 1;
 }
}

rngIntUtil.c

/**CFile***********************************************************************
  FileName    [rngRangeIntUtil.c]
  PackageName [rng]
  Synopsis    [Internal package utilities in the range package.]
  Description [ This has just one internal function called RngRangeIsOk.]
  SeeAlso     [rng.h rngInt.h rngUtil.c]
  Author      [Gitanjali Swamy]

  Copyright   [Copyright (c) 1994-1996 The Regents of the Univ. of California.
  All rights reserved.]
******************************************************************************/
#include "rngInt.h"

static char rcsid[] = "$Id: node5.html,v 1.1.1.1 2001/04/26 21:30:15 vis Exp $";
USE(rcsid);

/**AutomaticStart*************************************************************/
/**AutomaticEnd***************************************************************/

/*---------------------------------------------------------------------------*/
/* Definition of internal functions                                          */
/*---------------------------------------------------------------------------*/


/**Function********************************************************************
  Synopsis    [Check if a Rng_Range_t is well ordered.]
  Description [Given a Rng_Range_t , this function returns TRUE if it
  is a valid range, and FALSE if it is not.]
  SideEffects []
******************************************************************************/
boolean
RngRangeIsOK(Rng_Range_t *range)
{
  if (Rng_RangeReadBegin(range) <= Rng_RangeReadEnd(range)) {
    if (Rng_RangeReadBegin(range) => RNG_MIN) {
       if (Rng_RangeReadEnd(range) <= RNG_MAX) {
          return 1;
       }
    }
  }
  return 0;
}


Tom Shiple
Fri May 10 17:19:47 PDT 1996
Contact 
©2002-2018 U.C. Regents