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_string.h 00022 \brief Interface description of the default COSTA string component. 00023 00024 Utilities including most of the basic string operations and access to the string data itself. 00025 */ 00026 00027 #ifndef CTA_STRING_H 00028 #define CTA_STRING_H 00029 #include "cta_system.h" 00030 #include "cta_handles.h" 00031 #include "cta_datatypes.h" 00032 00033 /* String instance handle declared in cta_handles.h */ 00034 #ifdef __cplusplus 00035 extern "C" { 00036 #endif 00037 00038 /** \brief Create a new COSTA string instance. 00039 * 00040 * \param hstring O handle of created string 00041 * \return CTA_OK if successful 00042 */ 00043 CTAEXPORT int CTA_String_Create(CTA_String *hstring); 00044 00045 /** \brief Create a new COSTA string that is a copy of an existing one 00046 * 00047 * \param hto O receives the handle of the created string 00048 * \param hfrom I handle of string to copy 00049 * 00050 * \return CTA_OK if successful 00051 */ 00052 CTAEXPORT int CTA_String_Copy(CTA_String *hto, CTA_String hfrom); 00053 00054 /** \brief Free the COSTA string instance. 00055 * 00056 * \note 00057 * 00058 * \param hstring IO handle of the string instance, replaced by CTA_NULL on return 00059 * \return CTA_OK if successful 00060 */ 00061 CTAEXPORT int CTA_String_Free(CTA_String *hstring); 00062 00063 /** \brief Get the number of characters in string. 00064 * 00065 * \note The returned length is the number of characters excluding the 00066 * 0-character. 00067 * 00068 * \param hstring I handle of the string 00069 * \param len O receives the number of characters in string 00070 * \return CTA_OK if successful 00071 */ 00072 CTAEXPORT int CTA_String_GetLength(CTA_String hstring, int *len); 00073 00074 /** \brief Set the string to new content. 00075 * 00076 * \param hstring IO handle of the string 00077 * \param str I new content 00078 * \return CTA_OK if successful 00079 */ 00080 CTAEXPORT int CTA_String_Set(CTA_String hstring, const char *str); 00081 00082 /** \brief Get a copy of the string. 00083 * 00084 * \note It is the responsibility of the caller making str large enough to 00085 * hold the string and trailing 0-character. 00086 * 00087 * \param hstring I handle of the string 00088 * \param str O buffer that receives a copy of the string including trailing 0-character 00089 * \return CTA_OK if successful 00090 */ 00091 CTAEXPORT int CTA_String_Get(CTA_String hstring, char *str); 00092 00093 /** \brief Get the (scalar) value of a string 00094 * 00095 * \note It is the responsibility of the caller that parameter value is large enough to 00096 * hold the value as specified by the datatype. 00097 * 00098 * \param hstring I handle of the string 00099 * \param value O receives the value 00100 * \param datatype I data type of value 00101 * \return CTA_OK if successful 00102 */ 00103 CTAEXPORT int CTA_String_GetValue(CTA_String hstring, void *value, CTA_Datatype datatype); 00104 00105 00106 /** \brief Create new string that is a concatination of existing strings. 00107 * 00108 * \param istring IO handle of the string (first string in concatination) 00109 * and whole concatinated string on return 00110 * \param xstring I handle of the second string (extension string) 00111 * \return CTA_OK if successful 00112 */ 00113 CTAEXPORT int CTA_String_Conc(CTA_String istring, CTA_String xstring); 00114 00115 00116 /** \brief Get a pointer to the contents of the string (INTERNAL USE) 00117 * 00118 * \param hstring I handle of the string 00119 * \return pointer to the string contents 00120 */ 00121 CTAEXPORT char *CTAI_String_GetPtr(CTA_String hstring); 00122 00123 00124 /** \brief Imports string. 00125 * 00126 * Supports: pack objects (usrdata must be handle of pack object to import from) 00127 * 00128 * \param hstring IO handle of the string 00129 * \param usrdata I configuration of import 00130 * \return CTA_OK if successful 00131 * 00132 * \note Only CTA_Pack is currently supported fot usrdata 00133 */ 00134 CTAEXPORT int CTA_String_Import(CTA_String hstring, CTA_Handle usrdata); 00135 00136 /** \brief Exports length of string and string itself. 00137 * 00138 * Supports: pack objects (usrdata must be handle of pack object to export to) 00139 * 00140 * \param hstring I handle of the string 00141 * \param usrdata IO configuration of export 00142 * \return CTA_OK if successful 00143 * 00144 * \note Only CTA_Pack is currently supported fot usrdata 00145 */ 00146 CTAEXPORT int CTA_String_Export(CTA_String hstring, CTA_Handle usrdata); 00147 00148 /** \brief Check whether string is equal to COSTA string. 00149 * 00150 * 00151 * \param hstring I handle of the string 00152 * \param str0 I string to compare hsting with 00153 * \return CTA_TRUE/CTA_FALSE 00154 * 00155 * \note Only CTA_Pack is currently supported fot usrdata 00156 */ 00157 CTAEXPORT int CTA_String_Equals_Char(CTA_String hstring, const char *str0); 00158 00159 /** \brief Check whether two COSTA strings are equal. 00160 * 00161 * 00162 * \param hstring1 I handle of first string 00163 * \param hstring2 I handle of second string 00164 * \return CTA_TRUE/CTA_FALSE 00165 * 00166 * \note Only CTA_Pack is currently supported fot usrdata 00167 */ 00168 CTAEXPORT int CTA_Strings_Equal(CTA_String hstring1, CTA_String hstring2); 00169 00170 00171 /** \brief Create a duplication of a COSTA string 00172 * 00173 * \param hfrom I handle of string to copy 00174 * \param hto O handle of created string 00175 * \return CTA_OK if successful 00176 */ 00177 CTAEXPORT int CTA_String_Duplicate(CTA_String hfrom, CTA_String *hto); 00178 00179 /*=====================================================================*/ 00180 #ifdef __cplusplus 00181 } 00182 #endif 00183 #endif 00184
1.6.1