Grid Application Toolkit A simple API for Grid Applications

Menu Home API-Specification API-Overview Status C Reference Manual Download Java Java-Reference General GridLab - WP-1 Links

GATString.h Go to the documentation of this file. /** @file GATString.h * Header file for the GATString class. * * A GATString represents a string of characters. * * @date $Date: 2004/03/24 19:30:58 $ * * @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATString.h,v 1.12 2004/03/24 19:30:58 hartmutkaiser Exp $ * * Copyright (C) Kelly Davis * This file is part of the GAT Engine. * Contributed by Kelly Davis <kdavis@aei.mpg.de>. * * Use, modification and distribution is subject to the Gridlab Software * License. (See accompanying file GLlicense.txt or copy at * http://www.gridlab.org/GLlicense.txt) */ #ifndef _GATSTRING_H_ #define _GATSTRING_H_ 1 #include "GATType.h" #include "GATInternal.h" #ifdef __cplusplus extern "C" { #endif /* Declare the converters to/from GATObject */ GATOBJECT_DECLARE_CONVERTERS(GATString); /** * <p> * This function creates a new #GATString instance. This function constructs a new * #GATString by decoding the specified array of bytes, @c byteArray, using the * specified encoding, @c encoding. The number of charaters in the new #GATString * is a function of the encoding, and hence may not be equal to the length of the * byte array, @c byteArray. * </p> * <p> * The @c encoding passed to this function is a array of bytes which represents * the name of the encoding in which the byte array @c byteArray is encoded. The * encoding itself is encoded using the encoding @c ASCII. The supported encodings * are as follows: * </p> * <p> * @htmlonly * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="10%"></td><td width="90%"> * European languages</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="21%"></td><td width="79%"> * ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16}, KOI8-R, * KOI8-U, KOI8-RU, CP{1250,1251,1252,1253,1254,1257}, * CP{850,866}, * Mac{Roman,CentralEurope,Iceland,Croatian,Romania}, * Mac{Cyrillic,Ukraine,Greek,Turkish}, Macintosh</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="10%"></td><td width="90%"> * Semitic languages</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="21%"></td><td width="79%"> * ISO-8859-{6,8}, CP{1255,1256}, CP862, * Mac{Hebrew,Arabic}</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="10%"></td><td width="90%"> * Japanese</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="21%"></td><td width="79%"> * EUC-JP, SHIFT_JIS, CP932, ISO-2022-JP, ISO-2022-JP-2, * ISO-2022-JP-1</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="10%"></td><td width="90%"> * Chinese</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="21%"></td><td width="79%"> * EUC-CN, HZ, GBK, GB18030, EUC-TW, BIG5, CP950, BIG5-HKSCS, * ISO-2022-CN, ISO-2022-CN-EXT</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="10%"></td><td width="90%"> * Korean</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="21%"></td><td width="79%"> * EUC-KR, CP949, ISO-2022-KR, JOHAB</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="10%"></td><td width="90%"> * Armenian</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="21%"></td><td width="79%"> * ARMSCII-8</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="10%"></td><td width="90%"> * Georgian</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="21%"></td><td width="79%"> * Georgian-Academy, Georgian-PS</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="10%"></td><td width="90%"> * Tajik</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="21%"></td><td width="79%"> * KOI8-T</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="10%"></td><td width="90%"> * Thai</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="21%"></td><td width="79%"> * TIS-620, CP874, MacThai</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="10%"></td><td width="90%"> * Laotian</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="21%"></td><td width="79%"> * MuleLao-1, CP1133</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="10%"></td><td width="90%"> * Vietnamese</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="21%"></td><td width="79%"> * VISCII, TCVN, CP1258</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="10%"></td><td width="90%"> * Platform specifics</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="21%"></td><td width="79%"> * HP-ROMAN8, NEXTSTEP</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="10%"></td><td width="90%"> * Full Unicode</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="21%"></td><td width="79%"> * UTF-8</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="21%"></td><td width="79%"> * UCS-2, UCS-2BE, UCS-2LE</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="21%"></td><td width="79%"> * UCS-4, UCS-4BE, UCS-4LE</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="21%"></td><td width="79%"> * UTF-16, UTF-16BE, UTF-16LE</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="21%"></td><td width="79%"> * UTF-32, UTF-32BE, UTF-32LE</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="21%"></td><td width="79%"> * UTF-7</td></table> * * <table width="100%" border=0 rules="none" frame="void" * cols="2" cellspacing="0" cellpadding="0"> * <tr valign="top" align="left"> * <td width="21%"></td><td width="79%"> * C99, JAVA</td></table> * @endhtmlonly * </p> * <p> * If the passed @c byteArray is not encoded properly in the passed encoding * or if there is a problem in allocating memory, this function returns the * value NULL. * </p> * * @param byteArray The array of bytes encoded using @c encoding. * @param lengthInBytes The number of bytes in the passed array of bytes * @param encoding The encoding used to encode the passed array of bytes * @return On success a new #GATString representing the passed data */ GATString GATString_Create(const char *byteArray, GATuint32 lengthInBytes, const char *encoding); /** * This fucntion returns the type, a #GATType, of the passed #GATString_const. * This function will always return #GATType_GATString. * * @param string The #GATString_const to query * @return The #GATType of the passed @c string */ GATType GATString_GetType(GATString_const string); /** * <p> * This function determines if the two passed #GATString_const are equivalent. * Two #GATString_const instances are equivalent if they are both non-null and * represent the exact same sequence of characters. * </p> * <p> * If the two passed #GATString_const are equal and this function does not * encouter an error state of some sort, then the #GATBool pointed to by the * passed @c isequal parameter is set to #GATTrue. Otherwise this #GATBool * is set of #GATFalse. The completion status of this function is returned * through its return value. * </p> * * @param this The first #GATString_const to query * @param that The Second #GATString_const to query * @param isequal The query result * @return The completion status of this function */ GATResult GATString_Equals(GATString_const string, GATString_const that, GATBool *isequal); /** * This function returns a "deep clone" of the passed #GATString_const @c string. * This "deep clone" is returned in the variable @c stringClone. Furthermore, this * function returns its completion status, through its return value. * * @param string The #GATString_const to clone * @param stringClone The cloned #GATString_const * @return The completion status of this function */ GATResult GATString_Clone(GATString_const string, GATString *stringClone); /** * Destroys the #GATString instance * * @param string The #GATString to destroy. */ void GATString_Destroy(GATString *string); /** * This function returns the length in bytes of the passed #GATString_const's encoded * buffer. * * @param string The #GATString_const to query * @return The length in bytes of #GATString_const's encoded buffer, -1 upon NULL @c string */ GATuint32 GATString_GetLengthInBytes(GATString_const string); /** * This function returns the passed #GATString_const's encoded buffer. * * @param string The #GATString_const to query * @return The passed #GATString_const's encoded buffer, NULL upon NULL @c string */ const char * GATString_GetBuffer(GATString_const string); /** * This fucntion return the passed #GATString_const's encoding, itself encoded in ASCII. * * @param string The #GATString_const to query * @return The passed #GATString_const's encoding, itself encoded in ASCII, NULL upon NULL @c string */ const char * GATString_GetEncoding(GATString_const string); /** * <p> * This function translates the passed #GATString_const, @c string, from its * encoding to the encoding, @c encoding. The result is returned in @c result. * </p> * <p> * The supported encoding which may be passed to this function are the same * set of encodings as specified by the documentation for the function * #GATString_Create. * </p> * <p> * If an error occurs during translation, then @c result is set to NULL and * the error status is returned in this function's return value. Otherwise * the completion status of this function is returned through its return * value and @c result s set to point to the translated #GATString. * </p> * * @param string The #GATString_const to translate * @param newEncoding The target encoding * @param result The translated #GATString or NULL on failure * @return The completion status of this function */ GATResult GATString_Translate(GATString_const string, const char *newEncoding, GATString *result); /** * <p> * This function compares two strings lexicographically. The comparison is based * on the UTF-32 value of each character in the strings. The character sequence * represented by @c this #GATString_const instance is compared lexicographically * to the character sequence represented by the argument @c that #GATString_const. * The result is a negative integer if @c this #GATString_const lexicographically * precedes the argument @c that. The result is a positive integer if @c this * #GATString_const instance lexicographically follows the argument @c that. * </p> * <p> * This is the definition of lexicographic ordering. If two strings are different, * then either they have different characters at some index that is a valid index * for both strings, or their lengths are different, or both. If they have different * characters at one or more index positions, let k be the smallest such index; then * the string whose character at position k has the smaller value, as determined * by using the < operator, lexicographically precedes the other string. In this * case, #GATString_CompareTo returns the difference of the two character values at * position k in the two string. * </p> * <p> * If there is no index position at which they differ, then the shorter string * lexicographically precedes the longer string. In this case, #GATString_CompareTo * returns the difference of number of bytes in the encoded lengths of the strings * in the UTF-32 encoding. * </p> * <p> * If any error occurs durring the processing of this function an appropriate * error code is returned through the return value of this function and the * value pointed to by @c comparrison is 0. * </p> * * @param this The first #GATString_const to compare * @param that The second #GATString_const to compare * @param comparrison The result of the comparrison or 0 on error * @return The completion status of this function */ GATResult GATString_CompareTo(GATString_const lhs, GATString_const rhs, int *comparrison); /** * <p> * This function determines if the passed #GATString_const @c string ends with the * passed #GATString_const @c query. If it does and no error occurs, then the #GATBool * pointed to by @c result is set to #GATTrue. If it does not and no error occurs, * then the #GATBool pointed to by @c result is set to #GATFalse. * </p> * <p> * If there is an error, then the #GATBool pointed to by @c result is set to GATFalse * and the error is returned in this function's return value. * </p> * * @param string The #GATString_const to query * @param query The #GATString_const query string * @param result The #GATBool result of the query, GATFalse on error * @return The completion status of this function */ GATResult GATString_EndsWith(GATString_const string, GATString_const query, GATBool *result); /** * <p> * This function determines if the passed #GATString_const @c string starts with the * passed #GATString_const @c query. If it does and no error occurs, then the #GATBool * pointed to by @c result is set to #GATTrue. If it does not and no error occurs, * then the #GATBool pointed to by @c result is set to #GATFalse. * </p> * <p> * If there is an error, then the #GATBool pointed to by @c result is set to GATFalse * and the error is returned in this function's return value. * </p> * * @param string The #GATString_const to query * @param query The #GATString_const query string * @param result The #GATBool result of the query, GATFalse on error * @return The completion status of this function */ GATResult GATString_StartsWith(GATString_const string, GATString_const query, GATBool *result); /** * <p> * This function concatenats the passed #GATString_const @c that to the right side * of the passed #GATString_const @c this and returns the resulting #GATString by * way of the pointer @c result. * </p> * <p> * If an error occurs durring processings @c result is set to point to NULL and * the error status is returned through this function's return value. * </p> * * @param this The first #GATString_const to concatenate * @param that The second #GATString_const to concatenate * @param result The concatenation of @c this and @c that or NULL on error * @return The completion status of this function */ GATResult GATString_Concatenate(GATString_const str, GATString_const that, GATString *result); /** * <p> * This function returns the last index @c index of the passed #GATString_const @c query * in the passed @GATString_const string. If the passed #GATString_const @c string does * not contain the passed #GATString_const @c query, then @c index is set to point to a * value -1. * </p> * <p> * If an error occurs durring processing, then @c index is set to point to (GATuint32)(-1) * and the error code is returned as the return value of this function. * </p> * * @param string The #GATString_const to examine * @param query The #GATString_const to search for * @param queryIndex The last index of @query in @string or(GATuint32)(-1) * @return The completion status of this function */ GATResult GATString_LastIndexOf(GATString_const string, GATString_const query, GATuint32 *queryIndex); /** * <p> * This function returns the first index @c index of the passed #GATString_const @c query * in the passed @GATString_const string. If the passed #GATString_const @c string does * not contain the passed #GATString_const @c query, then @c index is set to point to a * value -1. * </p> * <p> * If an error occurs durring processing, then @c index is set to point to (GATuint32)(-1) * and the error code is returned as the return value of this function. * </p> * * @param string The #GATString_const to examine * @param query The #GATString_const to search for * @param index The first queryIndex of @query in @string or (GATuint32)(-1) * @return The completion status of this function */ GATResult GATString_FirstIndexOf(GATString_const string, GATString_const query, GATuint32 *queryIndex); /** * <p> * This function creates a new #GATString which is a substring of the passed #GATString_const * @c string. The first character in this substring is the @c start charcter in @c string. * The last charater is the charcter <code>finish - 1</code> in @c string. * </p> * <p> * If an error occurs durring processing, then @substring is set to point not to a new * #GATString but to NULL and the appropriate error code is returned through the return * value of this function. * </p> * * @param string The #GATString_const to query * @param start The starting index, inclusive * @param finish The finishing index, exclusive * @param substring The specified substring * @return The completion status of this function */ GATResult GATString_GetSubString(GATString_const string, GATuint32 start, GATuint32 end, GATString *substring); /** int GATString_GetInterface(GATString_const file, GATInterface iftype, void const **ifp) * @brief Get an interface supported by a GATString * * The function GATString_GetInterface allows to get a pointer to an * additional interface supported by this GATString. * * @param object The object to be asked for the new interface. * @param iftype The interface the object is to be asked for. * @param ifp The pointer, through which the result is to be returned. * * @return An error type. */ GATResult GATString_GetInterface(GATString_const file, GATInterface iftype, void const **ifp); /* GATSerialisable API */ #define GATSTRING_VERSION1 0x0100 #define GATSTRING_LASTVERSION GATSTRING_VERSION1 #define GATSTRING_MINOR_MASK 0x00ff /** int GATString_Serialise(GATString file, GATObject stream, GATBool clear_dirty) * @brief Serialise a GATString object * * The function GATString_Serialise serialises the given GATString object into the * given stream. * * @param string The GATString object to serialise. * @param stream The stream interface to use for the serialisation. * @param clear_dirty If the clear_dirty parameter is set to GATTrue, the * internal dirty flag of this object is to be reset (no used here) * * @return An error code. */ GATResult GATString_Serialise(GATString string, GATObject stream, GATBool clear_dirty); /** GATString GATString_DeSerialise(GATContext context, GATObject stream, GATBool clear_dirty) * @brief De-serialise a GATString object * * The function GATString_DeSerialise de-serialises a streamed GATString object * from the given stream It constructs a new instance of the de-serialised * object. * * @param context The GAT context to be used for object construction. * @param stream The stream interface to use for the serialisation. * @param result The pointer to a variable, which receives the status code of * the operation. * * @return The newly constructed GATString object. */ GATString GATString_DeSerialise(GATContext context, GATObject stream, GATResult *result); /** GATString_GetIsDirty * * The function GATString_GetIsDirty retrieves the status of the dirty flag of * this GATString object. * * @param file The GATString object to inspect for its dirty status. * @param isdirty The pointer to a variable, which receives the dirty status. * * @return An error code. */ GATResult GATString_GetIsDirty(GATString_const file, GATBool *isdirty); #ifdef __cplusplus } #endif #endif /* _GATSTRING_H_ */