Title: cardfind


NAME
====
 ft_cardfind,ft_cardfindidx,ft_cardfindseq -Fitsy FITS card find routines.

SYNOPSIS
========
 

-
FITSCard ft_cardfind(FITSHead fits, FITSCard key, int add);
FITSCard ft_cardfindidx(FITSHead fits, FITSCard key, int *match);
FITSCard ft_cardfindseq(FITSHead fits, FITSCard key, int *match);


-
PARAMETERS
==========
  * #"FITSHead fits" - The FITS header to look in.
  * #"FITSCard key" - The card keyword to lookup.
  * #"int add" - If add is true the card will
      be added to the header if it is
      not found.
  * #"int *match" - Returns true if the card found is
      an exact match for the keyword requested.

DESCRIPTION
===========
 Routines to find FITS cards in a FITS headers data structure.

 ft_cardfind
 -----------
 Find a FITS card in the header.
 
 #cardfind will use the index if is has been created otherwise
 it searches sequentially through the header to find the card.

 ft_cardfindidx
 --------------
 Find a FITS card in the header using an index.
 
 If the header is not indexed an index is created for it.

 ft_cardfindseq
 --------------
 Find a card in the FITS header using sequential search.
 
 If the requested card is a FITS indexed keyword and an exact match
 is not found, the last card of that type is returned and
 match is set to 0.

EXAMPLES
========

+

		/* Declair some fitsy types.
		 *-/
		#FITSHead	fits;
		#FITSCard	foo;
		#FITSCard	goo;
		#FITSBuff	key;

	/* Look up a card using sequential search.
	 *-/
	#ft_cardkey(key, "FOO");
	foo = #ft_cardfind(fits, key, 0);

	/* This is the same thing.  But the card is added to the header
	   if it isn't found.  This will also invalidate the index if
	   there is one.
	 *-/
	#ft_cardkey(key, "FOO");
	foo = #ft_cardfind(fits, key, 1);

	/* Now index the header so that searches are faster.  #ft_cardfind
	   will automatically use the index if its valid.
	 *-/
	#ft_index(fits);
	#ft_cardkey(key, "GOO", 0);
	goo = #ft_cardfind(fits, key, 0);

+