; docformat = 'rst'
;+
; This function generate a series of orbit_info structures.
; 
; :Examples:
;   Commonly, if you already have orbits in the orbit table and you want 
;   more, call it like this:
;   
;   last_orbit=get_last_orbit_info()
;   more_orbits=generate_orbit_info(last_orbit.stop_time,last_orbit.orbit_number+1,end_time)
;-
;+
; :Params:
;   start_time : in ,required, type=double
;     Time of the beginning of the first orbit to generate. Assumes to be 
;     at ascending node.
;   first_orbit_number : in ,required, type=int
;     Orbit number of the first orbit to generate
;   end_time : in ,required, type=double
;     Generates orbits up to the one which overlaps this time.
;     NOTE: all times are in GPS microseconds.
;     
; :Keywords:
;   verbose : in, optional, type=boolean
;     Provides more detail when generating the orbit structures.
;     
; :Returns:
;   Returns an array of orbit_info structures.
;-
function generate_orbit_info, start_time, first_orbit_number, end_time, verbose=verbose
  
  if ~real_numeric_type(start_time) or ~real_numeric_type(first_orbit_number) or $
     ~real_numeric_type(end_time) then begin
     doc_library, 'generate_orbit_info'
     return, -1
  endif
  
  ; Keep a cache of the generated orbits so that it is not necessary to continually
  ;   recalculate them each time they are needed
  common cached_generated_orbits, $
    generated_orbits
  if ~keyword_set(generated_orbits) then generated_orbits = []
  
  ; Copy the input parameters so that they remain unchanged by this function
  orbit_start = start_time
  orbit_number = first_orbit_number
  stop_time = start_time
  
  ; Initially there is no result to return
  result = []
  
  ; Create new orbits until the orbit stop time exceeds the limit set
  ;   by the input parameter
  while stop_time lt end_time do begin
    if n_elements(generated_orbits) gt 0 then begin
      cached_orbit = where(generated_orbits.orbit_number eq orbit_number, n_orbits)
    endif else n_orbits = 0
    if n_orbits ge 1 then begin
      orbit_info = generated_orbits[cached_orbit[0]]
      cached_or_new = 'Cached'
    endif else begin
      orbit_info=find_next_orbit(orbit_start)
      orbit_info.orbit_number=orbit_number
      generated_orbits = n_elements(generated_orbits) gt 0 ? [generated_orbits, orbit_info] : [orbit_info]
      cached_or_new = '   New'
    endelse
    orbit_start = orbit_info.stop_time
    stop_time = orbit_info.stop_time
    orbit_number++
    result= n_elements(result) gt 0 ? [result,orbit_info] : [orbit_info]
    if keyword_set(verbose) || get_debug_level() gt 5 then $
      print, get_routine_name() + "  " + cached_or_new + " orbit #" + $
      Strtrim(string(orbit_info.orbit_number,format='(%"%d")'), 2) +", starting at " + $
      usec2vms(orbit_info.start_time)
  endwhile
  
  return,result
end