Load ncbi (6.1.20010709) into ncbi-tools6/branches/upstream/current.

1 files changed, 273 insertions, 72 deletions

diff --git a/api/explore.h b/api/explore.h
index 8ea6f704..30d3ed13 100644
--- a/api/explore.h
+++ b/api/explore.h
@@ -29,7 +29,7 @@
 *   
 * Version Creation Date: 6/30/98
 *
-* $Revision: 6.21 $
+* $Revision: 6.37 $
 *
 * File Description:  Reengineered and optimized exploration functions
 *                      to be used for future code
@@ -63,8 +63,8 @@ extern "C" {
 /*****************************************************************************
 *
 *   SeqMgrBioseqContext, SeqMgrSegmentContext, SeqMgrDescContext and SeqMgrFeatContext
-*     are data structures supporting the collection of bioseqs, parts of segmented bioseqs,
-*     descriptors, and features, respectively
+*     are data structures supporting the collection of bioseqs, parts of segmented
+*     bioseqs, descriptors, and features, respectively
 *
 *****************************************************************************/
 
@@ -74,6 +74,7 @@ typedef struct seqmgrbioseqcontext {
   BioseqPtr     bsp;
   SeqEntryPtr   sep;
   BioseqSetPtr  bssp;
+  Int4          numsegs;
   Pointer       userdata;
                           /* the following fields are for internal use only */
   Pointer       omdp;
@@ -117,6 +118,7 @@ typedef struct seqmgrfeatcontext {
   CharPtr       label;
   Int4          left;
   Int4          right;
+  Int4          dnaStop;
   Boolean       partialL;
   Boolean       partialR;
   Boolean       farloc;
@@ -140,10 +142,16 @@ typedef struct seqmgrfeatcontext {
 *
 *****************************************************************************/
 
-NLM_EXTERN Uint2 LIBCALL SeqMgrIndexFeatures PROTO((Uint2 entityID, Pointer ptr));
+NLM_EXTERN Uint2 LIBCALL SeqMgrIndexFeatures (
+  Uint2 entityID,
+  Pointer ptr
+);
+
 
 /*****************************************************************************
 *
+*   To find the best protein feature for a CDS, first call SeqMgrGetProtXref.
+*     If it is NULL, call SeqMgrGetBestProteinFeature.
 *   SeqMgrGetBestProteinFeature and SeqMgrGetCDSgivenProduct take a protein
 *     bioseq to get the best protein feature or encoding CDS
 *   SeqMgrGetRNAgivenProduct takes an mRNA (cDNA) bioseq and gets the encoding
@@ -151,14 +159,24 @@ NLM_EXTERN Uint2 LIBCALL SeqMgrIndexFeatures PROTO((Uint2 entityID, Pointer ptr)
 *
 *****************************************************************************/
 
-NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetBestProteinFeature PROTO((BioseqPtr bsp,
-                                                                 SeqMgrFeatContext PNTR context));
+NLM_EXTERN ProtRefPtr LIBCALL SeqMgrGetProtXref (
+  SeqFeatPtr sfp
+);
+
+NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetBestProteinFeature (
+  BioseqPtr bsp,
+  SeqMgrFeatContext PNTR context
+);
 
-NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetCDSgivenProduct PROTO((BioseqPtr bsp,
-                                                              SeqMgrFeatContext PNTR context));
+NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetCDSgivenProduct (
+  BioseqPtr bsp,
+  SeqMgrFeatContext PNTR context
+);
 
-NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetRNAgivenProduct PROTO((BioseqPtr bsp,
-                                                              SeqMgrFeatContext PNTR context));
+NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetRNAgivenProduct (
+  BioseqPtr bsp,
+  SeqMgrFeatContext PNTR context
+);
 
 /*****************************************************************************
 *
@@ -170,12 +188,18 @@ NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetRNAgivenProduct PROTO((BioseqPtr bsp,
 *
 *****************************************************************************/
 
-NLM_EXTERN GeneRefPtr LIBCALL SeqMgrGetGeneXref PROTO((SeqFeatPtr sfp));
+NLM_EXTERN GeneRefPtr LIBCALL SeqMgrGetGeneXref (
+  SeqFeatPtr sfp
+);
 
-NLM_EXTERN Boolean LIBCALL SeqMgrGeneIsSuppressed PROTO((GeneRefPtr grp));
+NLM_EXTERN Boolean LIBCALL SeqMgrGeneIsSuppressed (
+  GeneRefPtr grp
+);
 
-NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingGene PROTO((SeqLocPtr slp,
-                                                              SeqMgrFeatContext PNTR context));
+NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingGene (
+  SeqLocPtr slp,
+  SeqMgrFeatContext PNTR context
+);
 
 /*****************************************************************************
 *
@@ -186,17 +210,25 @@ NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingGene PROTO((SeqLocPtr slp,
 *
 *****************************************************************************/
 
-NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingmRNA PROTO((SeqLocPtr slp,
-                                                              SeqMgrFeatContext PNTR context));
+NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingmRNA (
+  SeqLocPtr slp,
+  SeqMgrFeatContext PNTR context
+);
 
-NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingCDS PROTO((SeqLocPtr slp,
-                                                             SeqMgrFeatContext PNTR context));
+NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingCDS (
+  SeqLocPtr slp,
+  SeqMgrFeatContext PNTR context
+);
 
-NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingPub PROTO((SeqLocPtr slp,
-                                                             SeqMgrFeatContext PNTR context));
+NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingPub (
+  SeqLocPtr slp,
+  SeqMgrFeatContext PNTR context
+);
 
-NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingSource PROTO((SeqLocPtr slp,
-                                                                SeqMgrFeatContext PNTR context));
+NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingSource (
+  SeqLocPtr slp,
+  SeqMgrFeatContext PNTR context
+);
 
 /*****************************************************************************
 *
@@ -214,13 +246,20 @@ NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingSource PROTO((SeqLocPtr slp,
 *
 *****************************************************************************/
 
-NLM_EXTERN ValNodePtr LIBCALL SeqMgrGetNextDescriptor PROTO((BioseqPtr bsp, ValNodePtr curr,
-                                                             Uint1 seqDescChoice,
-                                                             SeqMgrDescContext PNTR context));
-
-NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetNextFeature PROTO((BioseqPtr bsp, SeqFeatPtr curr,
-                                                          Uint1 seqFeatChoice, Uint1 featDefChoice,
-                                                          SeqMgrFeatContext PNTR context));
+NLM_EXTERN ValNodePtr LIBCALL SeqMgrGetNextDescriptor (
+  BioseqPtr bsp,
+  ValNodePtr curr,
+  Uint1 seqDescChoice,
+  SeqMgrDescContext PNTR context
+);
+
+NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetNextFeature (
+  BioseqPtr bsp,
+  SeqFeatPtr curr,
+  Uint1 seqFeatChoice,
+  Uint1 featDefChoice,
+  SeqMgrFeatContext PNTR context
+);
 
 /*****************************************************************************
 *
@@ -229,13 +268,25 @@ NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetNextFeature PROTO((BioseqPtr bsp, SeqFeat
 *
 *****************************************************************************/
 
-typedef Boolean (LIBCALLBACK *SeqMgrBioseqExploreProc) PROTO((BioseqPtr bsp, SeqMgrBioseqContextPtr context));
+typedef Boolean (LIBCALLBACK *SeqMgrBioseqExploreProc) (
+  BioseqPtr bsp,
+  SeqMgrBioseqContextPtr context
+);
 
-typedef Boolean (LIBCALLBACK *SeqMgrSegmentExploreProc) PROTO((SeqLocPtr slp, SeqMgrSegmentContextPtr context));
+typedef Boolean (LIBCALLBACK *SeqMgrSegmentExploreProc) (
+  SeqLocPtr slp,
+  SeqMgrSegmentContextPtr context
+);
 
-typedef Boolean (LIBCALLBACK *SeqMgrDescExploreProc) PROTO((ValNodePtr sdp, SeqMgrDescContextPtr context));
+typedef Boolean (LIBCALLBACK *SeqMgrDescExploreProc) (
+  ValNodePtr sdp,
+  SeqMgrDescContextPtr context
+);
 
-typedef Boolean (LIBCALLBACK *SeqMgrFeatExploreProc) PROTO((SeqFeatPtr sfp, SeqMgrFeatContextPtr context));
+typedef Boolean (LIBCALLBACK *SeqMgrFeatExploreProc) (
+  SeqFeatPtr sfp,
+  SeqMgrFeatContextPtr context
+);
 
 /*****************************************************************************
 *
@@ -243,33 +294,77 @@ typedef Boolean (LIBCALLBACK *SeqMgrFeatExploreProc) PROTO((SeqFeatPtr sfp, SeqM
 *     SeqMgrExploreFeatures use the bioseq feature indices to quickly present
 *     desired items to the user-supplied callback function, stopping if the callback
 *     returns FALSE
-*   In contrast to the SeqMgrGetNext functions, the SeqMgrExplore function callbacks pass
-*     a pointer to the SeqMgr[Bioseq/Segment/Desc/Feat]Context data structures held by the
-*     explore function, not on the calling function's stack
-*   If the filter parameters are NULL, every feature or descriptor is returned, otherwise
-*     the array lengths should be SEQDESCR_MAX, SEQFEAT_MAX, and FEATDEF_MAX, and the
-*     elements are from the Seq_descr_, SEQFEAT_, and FEATDEF_ lists
+*   In contrast to the SeqMgrGetNext functions, the SeqMgrExplore function callbacks
+*     pass a pointer to the SeqMgr[Bioseq/Segment/Desc/Feat]Context data structures
+*     held by the explore function, not on the calling function's stack
+*   If the filter parameters are NULL, every feature or descriptor is returned,
+*     otherwise the array lengths should be SEQDESCR_MAX, SEQFEAT_MAX, and
+*     FEATDEF_MAX, and the elements are from the Seq_descr_, SEQFEAT_, and FEATDEF_
+*     lists
 *   It is expected that these calls would be flanked by BioseqLock and BioseqUnlock,
 *     so object manager reload could ensure that pointers are valid within the loop,
 *     but these explore functions can work on cached-out records
+*   All of these functions return the number of times the callback was called
 *
 *****************************************************************************/
 
-NLM_EXTERN Boolean LIBCALL SeqMgrExploreBioseqs PROTO((Uint2 entityID, Pointer ptr, Pointer userdata,
-                                                       SeqMgrBioseqExploreProc userfunc,
-                                                       Boolean nucs, Boolean prots, Boolean parts));
+NLM_EXTERN Int2 LIBCALL SeqMgrExploreBioseqs (
+  Uint2 entityID,
+  Pointer ptr,
+  Pointer userdata,
+  SeqMgrBioseqExploreProc userfunc,
+  Boolean nucs,
+  Boolean prots,
+  Boolean parts
+);
+
+NLM_EXTERN Int2 LIBCALL SeqMgrExploreSegments (
+  BioseqPtr bsp,
+  Pointer userdata,
+  SeqMgrSegmentExploreProc userfunc
+);
+
+NLM_EXTERN Int2 LIBCALL SeqMgrExploreDescriptors (
+  BioseqPtr bsp,
+  Pointer userdata,
+  SeqMgrDescExploreProc userfunc,
+  BoolPtr seqDescFilter
+);
+
+NLM_EXTERN Int2 LIBCALL SeqMgrExploreFeatures (
+  BioseqPtr bsp,
+  Pointer userdata,
+  SeqMgrFeatExploreProc userfunc,
+  SeqLocPtr locationFilter,
+  BoolPtr seqFeatFilter,
+  BoolPtr featDefFilter
+);
 
-NLM_EXTERN Boolean LIBCALL SeqMgrExploreSegments PROTO((BioseqPtr bsp, Pointer userdata,
-                                                        SeqMgrSegmentExploreProc userfunc));
-
-NLM_EXTERN Boolean LIBCALL SeqMgrExploreDescriptors PROTO((BioseqPtr bsp, Pointer userdata,
-                                                          SeqMgrDescExploreProc userfunc,
-                                                          BoolPtr seqDescFilter));
+/*****************************************************************************
+*
+*   SeqMgrGetFeatureByLabel returns the a feature with the desired label
+*   If desired, place a SeqMgrFeatContext data structure on the stack, and pass
+*     in &context as the last parameter
+*   SeqMgrGetNextFeatureByLabel works like SeqMgrGetNextFeature, except that
+*     the order is by alphabetized label, not by chromosomal position
+*
+*****************************************************************************/
 
-NLM_EXTERN Boolean LIBCALL SeqMgrExploreFeatures PROTO((BioseqPtr bsp, Pointer userdata,
-                                                        SeqMgrFeatExploreProc userfunc,
-                                                        SeqLocPtr locationFilter,
-                                                        BoolPtr seqFeatFilter, BoolPtr featDefFilter));
+NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetFeatureByLabel (
+  BioseqPtr bsp,
+  CharPtr label,
+  Uint1 seqFeatChoice,
+  Uint1 featDefChoice,
+  SeqMgrFeatContext PNTR context
+);
+
+NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetNextFeatureByLabel (
+  BioseqPtr bsp,
+  SeqFeatPtr curr,
+  Uint1 seqFeatChoice,
+  Uint1 featDefChoice,
+  SeqMgrFeatContext PNTR context
+);
 
 /*****************************************************************************
 *
@@ -282,34 +377,124 @@ NLM_EXTERN Boolean LIBCALL SeqMgrExploreFeatures PROTO((BioseqPtr bsp, Pointer u
 *
 *****************************************************************************/
 
-NLM_EXTERN ValNodePtr LIBCALL SeqMgrGetDesiredDescriptor PROTO((Uint2 entityID, BioseqPtr bsp,
-                                                                Uint2 itemID, Uint2 index, ValNodePtr sdp,
-                                                                SeqMgrDescContext PNTR context));
+NLM_EXTERN ValNodePtr LIBCALL SeqMgrGetDesiredDescriptor (
+  Uint2 entityID,
+  BioseqPtr bsp,
+  Uint2 itemID,
+  Uint2 index,
+  ValNodePtr sdp,
+  SeqMgrDescContext PNTR context
+);
+
+NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetDesiredFeature (
+  Uint2 entityID,
+  BioseqPtr bsp,
+  Uint2 itemID,
+  Uint2 index,
+  SeqFeatPtr sfp,
+  SeqMgrFeatContext PNTR context
+);
+
+/*****************************************************************************
+*
+*   SeqMgrVisitDescriptors and SeqMgrVisitFeatures visit all descriptors or
+*     features in an entity in order of itemID, which is assigned by order of
+*     packaging within the record
+*   Both of these functions return the number of times the callback was called
+*
+*****************************************************************************/
+
+NLM_EXTERN Int2 LIBCALL SeqMgrVisitDescriptors (
+  Uint2 entityID,
+  Pointer userdata,
+  SeqMgrDescExploreProc userfunc,
+  BoolPtr seqDescFilter
+);
+
+NLM_EXTERN Int2 LIBCALL SeqMgrVisitFeatures (
+  Uint2 entityID,
+  Pointer userdata,
+  SeqMgrFeatExploreProc userfunc,
+  BoolPtr seqFeatFilter,
+  BoolPtr featDefFilter
+);
+
+/*****************************************************************************
+*
+*   BioseqFindFromSeqLoc finds the segmented bioseq if location is join on parts,
+*     and does so even if some of the intervals are far accessions.
+*
+*****************************************************************************/
 
-NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetDesiredFeature PROTO((Uint2 entityID, BioseqPtr bsp,
-                                                             Uint2 itemID, Uint2 index, SeqFeatPtr sfp,
-                                                             SeqMgrFeatContext PNTR context));
+NLM_EXTERN BioseqPtr BioseqFindFromSeqLoc (
+  SeqLocPtr loc
+);
+
+/*****************************************************************************
+*
+*   SeqMgrGetParentOfPart returns the segmented bioseq parent of a part bioseq,
+*     and fills in the context structure.
+*
+*****************************************************************************/
+
+NLM_EXTERN BioseqPtr LIBCALL SeqMgrGetParentOfPart (
+  BioseqPtr bsp,
+  SeqMgrSegmentContext PNTR context
+);
+
+/*****************************************************************************
+*
+*   SeqMgrGetBioseqContext fills in the context structure for any bioseq.
+*
+*****************************************************************************/
+
+NLM_EXTERN Boolean LIBCALL SeqMgrGetBioseqContext (
+  BioseqPtr bsp,
+  SeqMgrBioseqContext PNTR context
+);
 
 /*****************************************************************************
 *
 *   SeqMgrBuildFeatureIndex builds a sorted array index for any feature type
 *     (gene, mRNA, CDS, publication, and biosource have built-in arrays)
-*   SeqMgrGetOverlappingFeature uses the array to find feature overlap,
-*     returning the position in the index
+*   SeqMgrGetOverlappingFeature uses the array, or a feature subtype (chocies
+*     are FEATDEF_GENE, FEATDEF_CDS, FEATDEF_mRNA, FEATDEF_PUB, or FEATDEF_BIOSRC)
+*     to find feature overlap, requiring either that the location be completely
+*     contained within the feature range, or merely that it be overlapped by the
+*     feature, and returns the position in the index
 *   SeqMgrGetFeatureInIndex gets an arbitrary feature indexed by the array
 *
 *****************************************************************************/
 
-NLM_EXTERN VoidPtr LIBCALL SeqMgrBuildFeatureIndex PROTO((BioseqPtr bsp, Int4Ptr num,
-                                                          Uint1 seqFeatChoice, Uint1 featDefChoice));
-
-NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingFeature PROTO((SeqLocPtr slp, VoidPtr featarray,
-                                                                 Int4 numfeats, Int4Ptr position,
-                                                                 SeqMgrFeatContext PNTR context));
-
-NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetFeatureInIndex PROTO((BioseqPtr bsp, VoidPtr featarray,
-                                                             Int4 numfeats, Uint2 index,
-                                                             SeqMgrFeatContext PNTR context));
+#define SIMPLE_OVERLAP   0
+#define CONTAINED_WITHIN 1
+#define CHECK_INTERVALS  2
+#define INTERVAL_OVERLAP 3
+
+NLM_EXTERN VoidPtr LIBCALL SeqMgrBuildFeatureIndex (
+  BioseqPtr bsp,
+  Int4Ptr num,
+  Uint1 seqFeatChoice,
+  Uint1 featDefChoice
+);
+
+NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingFeature (
+  SeqLocPtr slp,
+  Uint2 subtype,
+  VoidPtr featarray,
+  Int4 numfeats,
+  Int4Ptr position,
+  Int2 overlapType,
+  SeqMgrFeatContext PNTR context
+);
+
+NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetFeatureInIndex (
+  BioseqPtr bsp,
+  VoidPtr featarray,
+  Int4 numfeats,
+  Uint2 index,
+  SeqMgrFeatContext PNTR context
+);
 
 /* the following functions are not frequently called by applications */
 
@@ -320,7 +505,9 @@ NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetFeatureInIndex PROTO((BioseqPtr bsp, Void
 *
 *****************************************************************************/
 
-NLM_EXTERN time_t LIBCALL SeqMgrFeaturesAreIndexed PROTO((Uint2 entityID));
+NLM_EXTERN time_t LIBCALL SeqMgrFeaturesAreIndexed (
+  Uint2 entityID
+);
 
 /*****************************************************************************
 *
@@ -329,8 +516,22 @@ NLM_EXTERN time_t LIBCALL SeqMgrFeaturesAreIndexed PROTO((Uint2 entityID));
 *
 *****************************************************************************/
 
-NLM_EXTERN Boolean LIBCALL SeqMgrClearFeatureIndexes PROTO((Uint2 entityID, Pointer ptr));
+NLM_EXTERN Boolean LIBCALL SeqMgrClearFeatureIndexes (
+  Uint2 entityID,
+  Pointer ptr
+);
+
+/*****************************************************************************
+*
+*   SeqMgrIndexFeaturesEx allows indexing on opposite strand for upside-down Web views
+*
+*****************************************************************************/
 
+NLM_EXTERN Uint2 LIBCALL SeqMgrIndexFeaturesEx (
+  Uint2 entityID,
+  Pointer ptr,
+  Boolean flip
+);
 
 
 #ifdef __cplusplus