cta_time.h

Go to the documentation of this file.
00001 /*
00002 COSTA: Problem solving environment for data assimilation
00003 Copyright (C) 2005  Nils van Velzen
00004 
00005 This library is free software; you can redistribute it and/or
00006 modify it under the terms of the GNU Lesser General Public
00007 License as published by the Free Software Foundation; either
00008 version 2.1 of the License, or (at your option) any later version.
00009 
00010 This library is distributed in the hope that it will be useful,
00011 but WITHOUT ANY WARRANTY; without even the implied warranty of
00012 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00013 Lesser General Public License for more details.
00014 
00015 You should have received a copy of the GNU Lesser General Public
00016 License along with this library; if not, write to the Free Software
00017 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
00018 */
00019 
00020 /**
00021 \file  cta_time.h
00022 \brief Interface description of the default COSTA time component.
00023 
00024 A time object describes a time span (time of start, time of end). Utility functions are provided for changing and evaluating or comparing time spans.
00025 */
00026 
00027 #ifndef CTA_TIME_H
00028 #define CTA_TIME_H
00029 #include "cta_system.h"
00030 #include "cta_handles.h"
00031 #include "cta_datatypes.h"
00032 /* Function Handle */
00033 #ifdef __cplusplus
00034 extern "C" {
00035 #endif
00036 
00037 typedef CTA_Handle CTA_Time;
00038 
00039 /* functions */
00040 
00041 /** \brief Create a time object.
00042  *
00043  * \param htime  O  receives handle of newly created time object
00044  *
00045  * \return error status: CTA_OK if successful
00046  */
00047 CTAEXPORT int CTA_Time_Create(CTA_Time *htime);
00048 
00049 /** \brief Free a time object.
00050  *
00051  * \param htime    IO handle of time object to be freed, replaced by CTA_NULL on return.
00052  *
00053  * \return error status: CTA_OK if successful
00054  */
00055 CTAEXPORT int CTA_Time_Free(CTA_Time *htime);
00056 
00057 /** \brief Set the time span.
00058  *
00059  * \param htime    IO time object of which to set time span
00060  * \param tstart   I  starting time
00061  * \param tend     I  ending time
00062  *
00063  * \return error status: CTA_OK if successful
00064  */
00065 CTAEXPORT int CTA_Time_SetSpan(CTA_Time htime,double tstart, double tend);
00066 
00067 /** \brief Get the time span.
00068  *
00069  * \param htime    I  time object of which to get time span
00070  * \param tstart   O  receives the starting time
00071  * \param tend     O  receives ending time
00072  *
00073  * \return error status: CTA_OK if successful
00074  */
00075 CTAEXPORT int CTA_Time_GetSpan(CTA_Time htime,double *tstart, double *tend);
00076 
00077 /** \brief Set the time step.
00078  *
00079  * \param htime    IO time object of which to set time step
00080  * \param tstep    I  new time step
00081  *
00082  * \return error status: CTA_OK if successful
00083  */
00084 CTAEXPORT int CTA_Time_SetStep(CTA_Time htime,double tstep);
00085 
00086 /** \brief Get time step.
00087  *
00088  * \param htime    IO time object of which to get time step
00089  * \param tstep    O  receives time step
00090  *
00091  * \return error status: CTA_OK if successful
00092  */
00093 CTAEXPORT int CTA_Time_GetStep(CTA_Time htime,double *tstep);
00094 
00095 /** \brief Count number of timesteps in time 
00096  *
00097  * \param htime    I time object (see function description)
00098  * \param nstep    O number of timesteps
00099  *
00100  * \return error status: CTA_OK if successful
00101  *
00102  * \note number of steps is rounded to nearest integer
00103  */
00104 CTAEXPORT int CTA_Time_CountSteps(CTA_Time htime, int *nsteps);
00105 
00106 /** \brief Get interval of i-th step
00107  *
00108  * \param htime    I time object (see function description)
00109  * \param istep    I interval of step
00110  * \param nstep    O number of timesteps
00111  *
00112  * \return error status: CTA_OK if successful
00113  *
00114  * \note intervals are counted from 1 to nsteps
00115  */
00116 CTAEXPORT int CTA_Time_GetTimeStep(CTA_Time htime, int istep, CTA_Time htime_step);
00117 
00118 /** \brief Check whether htimesub is within time span of htime.
00119  *
00120  * \param htimesub I time object (see function description)
00121  * \param htime    I time object (see function description)
00122  * \param inspan   O receives TRUE if htimesub is within time span of htime or FALSE otherwise
00123  *
00124  * \return error status: CTA_OK if successful
00125  */
00126 CTAEXPORT int CTA_Time_InSpan(CTA_Time htimesub, CTA_Time htime,  BOOL *inspan);
00127 
00128 /** \brief Check whether time step of time object equals t
00129  *
00130  * \param htime    I time object
00131  * \param t        I time step to compare
00132  * \param isstep   O receives TRUE if t equals time step of time object or FALSE otherwise
00133  *
00134  * \return error status: CTA_OK if successful
00135  */
00136 CTAEXPORT int CTA_Time_IsStep(CTA_Time htime, double t,  BOOL *isstep);
00137 
00138 /** \brief Copy a time object.
00139  *
00140  * \param hfrom    I time object to copy from
00141  * \param hto      O handle of time object that receives copy, must exist before calling
00142  * \return error status: CTA_OK if successful
00143  */
00144 CTAEXPORT int CTA_Time_Copy(CTA_Time hfrom, CTA_Time hto);
00145 
00146 /** \brief Export a time object.
00147  * exports the whole internal state of the time object to given target
00148  * CTA_FILE will export the time component in a MATLAB/OCTAVE readable form
00149  * CTA_PACK will pack the content
00150  *
00151  * \param htime    I time object to export
00152  * \param hexport  I target for export (CTA_FILE or CTA_PACK)
00153  * \return error status: CTA_OK if successful
00154  */
00155 CTAEXPORT int CTA_Time_Export(CTA_Time htime, CTA_Handle hexport);
00156 
00157 /** \brief Import a time object.
00158  * imports the whole internal state of the time object from given source
00159  *
00160  * \param htime    I time object to import to 
00161  * \param hexport  I source of import (CTA_PACK)
00162  * \return error status: CTA_OK if successful
00163  */
00164 CTAEXPORT int CTA_Time_Import(CTA_Time htime, CTA_Handle himport);
00165 
00166 
00167 /** \brief Returns whether time object describes an timespan or a single
00168  * instance.
00169  *
00170  * \param htime    I time object to import to 
00171  * \param isspan   O time object is a time timespan (CTA_TRUE/CTA_FALSE) 
00172  * \return error status: CTA_OK if successful
00173  */
00174 CTAEXPORT int CTA_Time_IsSpan(CTA_Time htime, int *isspan);
00175 
00176 
00177 
00178 
00179 
00180 
00181 
00182 
00183 
00184 #ifdef __cplusplus
00185 }
00186 #endif
00187 
00188 
00189 #endif

Generated on Mon Apr 6 14:05:58 2009 for COSTA by  doxygen 1.5.2