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 nsteps 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 hstep O time step of model 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 hstep); 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 himport 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
1.6.1