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.c Go to the documentation of this file. /** @file GATString.c * Source file for the GATString class. * * A GATString represents a string of characters. * * @date $Date: 2004/04/02 12:31:58 $ * * @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATString.c,v 1.22 2004/04/02 12:31: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) */ static const char *rcsid = "$Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATString.c,v 1.22 2004/04/02 12:31:58 hartmutkaiser Exp $"; /* System Header Files */ #include <math.h> #include <stdio.h> #include <limits.h> #include <string.h> #include <stdlib.h> #include <errno.h> /* GAT Header Files */ #include "GATType.h" #include "GATString.h" #include "GATErrors.h" #include "GATInternal.h" #include "GATXdsWrapper.h" /* Header Files of Libraries Shipped with GAT */ #include <iconv.h> /* Macros */ /* Length chosen at random */ #define GATSTRING_BUFFER_LENGTH 1024 /* See RFC 2278: IANA Charset Registration Procedures. */ #define GATSTRING_MAX_ENCODING_LENGTH 41 /* Structures, unions and enums */ /* define the vtable types */ GATOBJECT_DEFINE_VTABLE(GATString); GATSERIALISABLE_DEFINE_VTABLE(GATString); /* Declare the converters to/from GATObject */ GATOBJECT_DEFINE_CONVERTERS(GATString); struct GATString_S { GATString_vtable *GATObject__vtable; GATString_ISerialisable_vtable *GATSerialisable__vtable; char *byteArray; GATuint32 lengthInBytes; char encoding[GATSTRING_MAX_ENCODING_LENGTH]; }; /* Static function prototypes */ /* File scope variables */ static GATString_vtable GATString__vtable = { GATString_GetType, GATString_Destroy, GATString_Equals, GATString_Clone, GATString_GetInterface, NULL }; static GATString_ISerialisable_vtable GATString_ISerialisable__vtable = { GATString_Serialise, GATString_DeSerialise, GATString_GetIsDirty }; /* External functions */ /** GATString_Register_GATSerialisable * The GATString_Register_GATSerialisable function registers the serialization * vtable with the GAT engine to allow generic object creation. * This function is called by the GAT engine, there is no need to use it * directly. */ GATResult GATString_Register_GATSerialisable() { return GATObject_Register_GATSerialisable(GATType_GATString, &GATString_ISerialisable__vtable); } /** * <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) { GATString this; this = NULL; if( (NULL != byteArray) && (0 < lengthInBytes) && (NULL != encoding) ) { this = (GATString) malloc( sizeof(*this) ); if(NULL != this) { float charPerByte; char *tempByteArray; size_t lengthInChars; this->byteArray = NULL; this->GATObject__vtable = &GATString__vtable; this->GATSerialisable__vtable = &GATString_ISerialisable__vtable; this->lengthInBytes = lengthInBytes; strncpy( this->encoding, encoding, GATSTRING_MAX_ENCODING_LENGTH ); (this->encoding)[GATSTRING_MAX_ENCODING_LENGTH - 1] = '\0'; /* Ensure encoding is null terminated */ charPerByte = ( 8 / CHAR_BIT ); lengthInChars = (size_t) ceil( lengthInBytes * charPerByte ); tempByteArray = (char *) malloc( lengthInChars ); if(NULL == tempByteArray) { GATString_Destroy( &this); } else { memcpy( (void *) tempByteArray, (const void *) byteArray, lengthInChars); this->byteArray = tempByteArray; } } } return this; } /** * 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) { GAT_UNUSED_PARAMETER(string); return GATType_GATString; } /** * <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 */ int GATString_Equals(GATString_const this, GATString_const that, GATBool *isequal) { int retval; GATuint32 count; GATString thisString; GATString thatString; GATuint32 thisArrayLength; GATuint32 thatArrayLength; retval = GAT_INVALID_PARAMETER; if( (NULL != this) && (NULL != that) && (NULL != isequal) ) { (*isequal) = GATFalse; if( GAT_SUCCESS == (retval = GATString_Translate(this, "UTF-32BE", &thisString)) ) { if( GAT_SUCCESS == (retval = GATString_Translate(that, "UTF-32BE", &thatString)) ) { thisArrayLength = (GATuint32) (GATString_GetLengthInBytes(thisString) / 4); /* Always integral as in UTF-32BE */ thatArrayLength = (GATuint32) (GATString_GetLengthInBytes(thatString) / 4); /* Always integral as in UTF-32BE */ if( thisArrayLength == thatArrayLength ) { GATBool equalFlag; const GATuint32 *thisArray; const GATuint32 *thatArray; equalFlag = GATTrue; thisArray = (const GATuint32 *) GATString_GetBuffer(thisString); thatArray = (const GATuint32 *) GATString_GetBuffer(thatString); for(count = 0; (count < thisArrayLength) && (GATTrue == equalFlag); count++) { if(thisArray[count] != thatArray[count]) { equalFlag = GATFalse; } } if( GATTrue == equalFlag ) { (*isequal) = GATTrue; } } GATString_Destroy(&thatString); } GATString_Destroy(&thisString); } } return retval; } /** * 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 */ int GATString_Clone(GATString_const string, GATString *stringClone) { int retval; retval = GAT_INVALID_PARAMETER; if( (NULL != string) && (NULL != stringClone) ) { GATuint32 length; const char *buffer; const char *encoding; (*stringClone) = NULL; retval = GAT_MEMORYFAILURE; buffer = GATString_GetBuffer(string); encoding = GATString_GetEncoding(string); length = GATString_GetLengthInBytes(string); (*stringClone) = GATString_Create(buffer, length, encoding); if( NULL != (*stringClone) ) { retval = GAT_SUCCESS; } } return retval; } /** * Destroys the #GATString instance * * @param string The #GATString to destroy. */ void GATString_Destroy(GATString *string) { if( (NULL != string) && (NULL != (*string)) ) { free( (*string)->byteArray ); free( (*string) ); (*string) = NULL; } } /** * 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) { GATuint32 lengthInBytes; lengthInBytes = -1; if(NULL != string) { lengthInBytes = string->lengthInBytes; } return lengthInBytes; } /** * 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) { const char *buffer; buffer = NULL; if(NULL != string) { buffer = string->byteArray; } return buffer; } /** * 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) { const char *encoding; encoding = NULL; if(NULL != string) { encoding = string->encoding; } return encoding; } /** * <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 encoding The target encoding * @param result The translated #GATString or NULL on failure * @return The completion status of this function */ int GATString_Translate(GATString_const string, const char *newEncoding, GATString *result) { int retval; retval = GAT_INVALID_PARAMETER; if( (NULL != string) && (NULL != newEncoding) && (NULL != result) ) { const char *oldEncoding; iconv_t conversionDescriptor; (*result) = NULL; retval = GAT_INVALID_ENCODING; oldEncoding = GATString_GetEncoding( string ); conversionDescriptor = iconv_open(newEncoding, oldEncoding); if( (iconv_t)(-1) != conversionDescriptor) { GATBool isDone; char *newBuffer; char *tempNewBuffer; const char *oldBuffer; const char *tempOldBuffer; GATuint32 oldBufferLengthInBytes; GATuint32 newBufferLengthInBytes; GATuint32 tempOldBufferLengthInBytes; GATuint32 tempNewBufferLengthInBytes; isDone = GATFalse; retval = GAT_MEMORYFAILURE; oldBuffer = GATString_GetBuffer(string); oldBufferLengthInBytes = GATString_GetLengthInBytes(string); tempOldBuffer = oldBuffer; tempOldBufferLengthInBytes = oldBufferLengthInBytes; tempNewBuffer = NULL; tempNewBufferLengthInBytes = 0; newBufferLengthInBytes = (GATuint32) GATSTRING_BUFFER_LENGTH * (CHAR_BIT / 8); newBuffer = (char *) malloc( newBufferLengthInBytes * (8 / CHAR_BIT) ); if(NULL != newBuffer) { size_t iconvRetVal; tempNewBuffer = newBuffer; tempNewBufferLengthInBytes = newBufferLengthInBytes; while(GATFalse == isDone) { newBuffer = tempNewBuffer; oldBuffer = tempOldBuffer; newBufferLengthInBytes = tempNewBufferLengthInBytes; oldBufferLengthInBytes = tempOldBufferLengthInBytes; iconvRetVal = (int) iconv(conversionDescriptor, &oldBuffer, (size_t *) &oldBufferLengthInBytes, &newBuffer, (size_t *) &newBufferLengthInBytes); if( ((size_t)(-1) == iconvRetVal) && (EILSEQ == errno) ) { isDone = GATTrue; retval = GAT_INVALID_ENCODING; } else if( (size_t)(-1) != iconvRetVal ) { isDone = GATTrue; retval = GAT_MEMORYFAILURE; (*result) = GATString_Create( tempNewBuffer, (tempNewBufferLengthInBytes - newBufferLengthInBytes), newEncoding ); if( NULL != (*result) ) { retval = GAT_SUCCESS; } } else if( ((size_t)(-1) == iconvRetVal) && (EINVAL == errno) ) { isDone = GATTrue; retval = GAT_INCOMPLETE_ENCODING; } else if( ((size_t)(-1) == iconvRetVal) && (E2BIG == errno) ) { tempNewBufferLengthInBytes = 2 * tempNewBufferLengthInBytes; if( NULL == (tempNewBuffer = (char *)realloc(tempNewBuffer, tempNewBufferLengthInBytes * (8 / CHAR_BIT))) ) { isDone = GATTrue; retval = GAT_MEMORYFAILURE; } } } } free( tempNewBuffer ); } iconv_close( conversionDescriptor ); } return retval; } /** * <p> * This function compares two strings lexicographically. The comparison is based * on the UTF-32BE 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-32BE 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 */ int GATString_CompareTo(GATString_const this, GATString_const that, int *comparrison) { int retval; retval = GAT_INVALID_PARAMETER; if( (NULL != this) && (NULL != that) && (NULL != comparrison) ) { GATString thisString; GATString thatString; (*comparrison) = 0; if( GAT_SUCCESS == (retval = GATString_Translate(this, "UTF-32BE", &thisString)) ) { if( GAT_SUCCESS == (retval = GATString_Translate(that, "UTF-32BE", &thatString)) ) { GATuint32 thisLengthInBytes; GATuint32 thatLengthInBytes; retval = GAT_SUCCESS; thisLengthInBytes = GATString_GetLengthInBytes(thisString); thatLengthInBytes = GATString_GetLengthInBytes(thatString); if( thisLengthInBytes == thatLengthInBytes ) { GATBool isDone; GATuint32 count; GATuint32 countMax; const GATuint32 *thisArray; const GATuint32 *thatArray; isDone = GATFalse; (*comparrison) = 0; thisArray = (const GATuint32 *) GATString_GetBuffer(thisString); thatArray = (const GATuint32 *) GATString_GetBuffer(thatString); countMax = (GATuint32) (thisLengthInBytes / 4); /* UTF-32BE implies this is an integer */ for(count = 0; (count < countMax) && (GATFalse == isDone); count++) { if(thisArray[count] != thatArray[count]) { isDone = GATTrue; (*comparrison) = (int) (thisArray[count] - thatArray[count]); } } } else { (*comparrison) = (int) (thisLengthInBytes - thatLengthInBytes); } GATString_Destroy( &thisString ); GATString_Destroy( &thatString ); } else { GATString_Destroy( &thisString ); } } } return retval; } /** * <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, queryString on error * @return The completion status of this function */ int GATString_EndsWith(GATString_const string, GATString_const query, GATBool *result) { int retval; retval = GAT_INVALID_PARAMETER; if( (NULL != string) && (NULL != query) && (NULL != result) ) { GATString queryString; GATString stringString; (*result) = GATFalse; if( GAT_SUCCESS == (retval =GATString_Translate(string, "UTF-32BE", &stringString)) ) { if( GAT_SUCCESS == (retval =GATString_Translate(query, "UTF-32BE", &queryString)) ) { GATuint32 queryLength; GATuint32 stringLength; retval = GAT_SUCCESS; queryLength = (GATuint32) (GATString_GetLengthInBytes(queryString) / 4); /* UTF-32BE implies this is an integer */ stringLength = (GATuint32) (GATString_GetLengthInBytes(stringString) / 4); /* UTF-32BE implies this is an integer */ if( queryLength <= stringLength ) { size_t charactersToCompare; const GATuint32 *queryArray; const GATuint32 *stringArray; const void *queryComparrisonStart; const void *stringComparrisonStart; queryArray = (const GATuint32 *) GATString_GetBuffer(queryString); stringArray = (const GATuint32 *) GATString_GetBuffer(stringString); queryComparrisonStart = (const void *) queryArray; charactersToCompare = (size_t) ( (queryLength * 4) * (8 / CHAR_BIT) ); stringComparrisonStart = (const void *) &( stringArray[stringLength - queryLength] ); if( 0 == memcmp(stringComparrisonStart, queryComparrisonStart, charactersToCompare) ) { (*result) = GATTrue; } } GATString_Destroy( &queryString ); GATString_Destroy( &stringString ); } else { GATString_Destroy( &stringString ); } } } return retval; } /** * <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 */ int GATString_StartsWith(GATString_const string, GATString_const query, GATBool *result) { int retval; retval = GAT_INVALID_PARAMETER; if( (NULL != string) && (NULL != query) && (NULL != result) ) { GATString queryString; GATString stringString; (*result) = GATFalse; if( GAT_SUCCESS == (retval = GATString_Translate(string, "UTF-32BE", &stringString)) ) { if( GAT_SUCCESS == (retval = GATString_Translate(query, "UTF-32BE", &queryString)) ) { GATuint32 queryLength; GATuint32 stringLength; retval = GAT_SUCCESS; queryLength = (GATuint32) (GATString_GetLengthInBytes(queryString) / 4); /* UTF-32BE implies this is an integer */ stringLength = (GATuint32) (GATString_GetLengthInBytes(stringString) / 4); /* UTF-32BE implies this is an integer */ if( queryLength <= stringLength ) { size_t charactersToCompare; const GATuint32 *queryArray; const GATuint32 *stringArray; const void *queryComparrisonStart; const void *stringComparrisonStart; queryArray = (const GATuint32 *) GATString_GetBuffer(queryString); stringArray = (const GATuint32 *) GATString_GetBuffer(stringString); queryComparrisonStart = (const void *) queryArray; stringComparrisonStart = (const void *) stringArray; charactersToCompare = (size_t) ( ((queryLength - 1) * 4) * (8 / CHAR_BIT) ); if( 0 == memcmp(stringComparrisonStart, queryComparrisonStart, charactersToCompare) ) { (*result) = GATTrue; } } GATString_Destroy( &queryString ); GATString_Destroy( &stringString ); } else { GATString_Destroy( &stringString ); } } } return retval; } /** * <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 */ int GATString_Concatenate(GATString_const this, GATString_const that, GATString *result) { int retval ; retval = GAT_INVALID_PARAMETER; if( (NULL != this) && (NULL != that) && (NULL != result) ) { GATString thisString; GATString thatString; (*result) = NULL; if( GAT_SUCCESS == (retval =GATString_Translate(this, "UTF-32BE", &thisString)) ) { if( GAT_SUCCESS == (retval =GATString_Translate(that, "UTF-32BE", &thatString)) ) { GATuint32 *resultBuffer; GATuint32 thisLengthInBytes; GATuint32 thatLengthInBytes; retval = GAT_MEMORYFAILURE; thisLengthInBytes = GATString_GetLengthInBytes( thisString ); thatLengthInBytes = GATString_GetLengthInBytes( thatString ); resultBuffer = (GATuint32 *) malloc( (thisLengthInBytes + thatLengthInBytes - 4) * (8 / CHAR_BIT) ); if(NULL != resultBuffer) { const GATuint32 *thisArray; const GATuint32 *thatArray; thisArray = (const GATuint32 *) GATString_GetBuffer( thisString ); thatArray = (const GATuint32 *) GATString_GetBuffer( thatString ); memcpy( (void *) resultBuffer, (const void *) thisArray, (size_t) (thisLengthInBytes - 4) * (8 / CHAR_BIT) ); memcpy( (void *) &(resultBuffer[(thisLengthInBytes - 4) / 4]), (const void *) thatArray, (size_t) (thatLengthInBytes) * (8 / CHAR_BIT) ); (*result) = GATString_Create( (const char *) resultBuffer, (thisLengthInBytes + thatLengthInBytes - 4), "UTF-32BE" ); if(NULL != (*result) ) { retval = GAT_SUCCESS; } } free(resultBuffer); GATString_Destroy( &thisString ); GATString_Destroy( &thatString ); } else { GATString_Destroy( &thisString ); } } } return retval; } /** * <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 */ int GATString_LastIndexOf(GATString_const string, GATString_const query, GATuint32 *queryIndex) { int retval; retval = GAT_INVALID_PARAMETER; if( (NULL != string) && (NULL != query) && (NULL != queryIndex) ) { GATString queryString; GATString stringString; (*queryIndex) = -1; if( GAT_SUCCESS == (retval =GATString_Translate(string, "UTF-32BE", &stringString)) ) { if( GAT_SUCCESS == (retval =GATString_Translate(query, "UTF-32BE", &queryString)) ) { GATuint32 queryLengthInBytes; GATuint32 stringLengthInBytes; retval = GAT_INVALID_PARAMETER; queryLengthInBytes = GATString_GetLengthInBytes( queryString ); stringLengthInBytes = GATString_GetLengthInBytes( stringString ); if( queryLengthInBytes <= stringLengthInBytes ) { GATBool isDone; GATuint32 count; GATuint32 countMaximum; size_t charsToCompare; const char *queryArray; const char *stringArray; retval = GAT_SUCCESS; queryArray = GATString_GetBuffer(queryString); stringArray = GATString_GetBuffer(stringString); isDone = GATFalse; charsToCompare = (size_t) ( (queryLengthInBytes - 4) * (8 / CHAR_BIT) ); countMaximum = (GATuint32) ( ((stringLengthInBytes - queryLengthInBytes) / 4) + 1 ); count = countMaximum; while( GATFalse == isDone ) { if( 0 == memcmp( (const void *) ( stringArray + (4 * count) - 4), (const void *) queryArray, charsToCompare ) ) { isDone = GATTrue; (*queryIndex) = (count - 1); } if( 1 == count ) { isDone = GATTrue; } else { count = count - 1; } } } GATString_Destroy( &queryString ); GATString_Destroy( &stringString ); } else { GATString_Destroy( &stringString ); } } } return retval; } /** * <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 */ int GATString_FirstIndexOf(GATString_const string, GATString_const query, GATuint32 *queryIndex) { int retval; retval = GAT_INVALID_PARAMETER; if( (NULL != string) && (NULL != query) && (NULL != queryIndex) ) { GATString queryString; GATString stringString; (*queryIndex) = -1; if( GAT_SUCCESS == (retval =GATString_Translate(string, "UTF-32BE", &stringString)) ) { if( GAT_SUCCESS == (retval =GATString_Translate(query, "UTF-32BE", &queryString)) ) { GATuint32 queryLengthInBytes; GATuint32 stringLengthInBytes; retval = GAT_INVALID_PARAMETER; queryLengthInBytes = GATString_GetLengthInBytes( queryString ); stringLengthInBytes = GATString_GetLengthInBytes( stringString ); if( queryLengthInBytes <= stringLengthInBytes ) { GATBool isDone; GATuint32 count; GATuint32 countMaximum; size_t charsToCompare; const char *queryArray; const char *stringArray; retval = GAT_SUCCESS; queryArray = GATString_GetBuffer(queryString); stringArray = GATString_GetBuffer(stringString); isDone = GATFalse; charsToCompare = (size_t) ( (queryLengthInBytes - 4) * (8 / CHAR_BIT) ); countMaximum = (GATuint32) ( ((stringLengthInBytes - queryLengthInBytes) / 4) + 1 ); count = 1; while( GATFalse == isDone ) { if( 0 == memcmp( (const void *) ( stringArray + (4 * count) - 4), (const void *) queryArray, charsToCompare ) ) { isDone = GATTrue; (*queryIndex) = (count - 1); } if( countMaximum == count) { isDone = GATTrue; } else { count = count + 1; } } } GATString_Destroy( &queryString ); GATString_Destroy( &stringString ); } else { GATString_Destroy( &stringString ); } } } return retval; } /** * <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 */ int GATString_GetSubString(GATString_const string, GATuint32 start, GATuint32 end, GATString *substring) { int retval; retval = GAT_INVALID_PARAMETER; if( (NULL != string) && (start < end) && (NULL != substring) ) { GATString stringString; (*substring) = NULL; if( GAT_SUCCESS == (retval =GATString_Translate(string, "UTF-32BE", &stringString)) ) { GATuint32 stringLengthInChars; GATuint32 stringLengthInBytes; retval = GAT_INVALID_PARAMETER; stringLengthInBytes = GATString_GetLengthInBytes(stringString); stringLengthInChars = (GATuint32) (stringLengthInBytes / 4); if( (start <= stringLengthInChars) && (end <= (stringLengthInChars + 1)) ) { const char *stringArray; GATuint32 *substringBuffer; size_t substringLengthInChar; GATuint32 substringLengthInBytes; size_t substringLengthInCharacters; retval = GAT_MEMORYFAILURE; substringLengthInCharacters = (end - start); substringLengthInBytes = (size_t) (substringLengthInCharacters * 4); stringArray = (const char *) GATString_GetBuffer(stringString); substringLengthInChar = (size_t) ( substringLengthInBytes * (8 / CHAR_BIT) ); substringBuffer = (GATuint32 *) malloc( substringLengthInChar ); if( NULL != substringBuffer ) { memcpy( (void *) substringBuffer, (const void *) ( stringArray + (start * 4) ), substringLengthInChar ); (*substring) = GATString_Create( (const char *) substringBuffer, substringLengthInBytes, "UTF-32BE"); if( NULL != (*substring) ) { retval = GAT_SUCCESS; } } free(substringBuffer); } GATString_Destroy( &stringString ); } } return retval; } /** int GATString_GetInterface(GATString_const file, GATInterface iftype, void const **ifp) * @brief Get an interface supported by a GATObject * * 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. */ int GATString_GetInterface(GATString_const string, GATInterface iftype, void const **ifp) { int retval = GAT_INVALID_PARAMETER; if (NULL != ifp) { *ifp = NULL; if (GATInterface_ISerialisable == iftype || GATInterface_IAdvertisable == iftype) { *ifp = (void const *) &string->GATSerialisable__vtable; retval = GAT_SUCCESS; } else { retval = GAT_NO_INTERFACE; } } return retval; } /* GATAdvertiseable API */ /** 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. */ int GATString_Serialise(GATString string, GATObject stream, GATBool clear_dirty) { int retval = GAT_INVALID_HANDLE; if (NULL != string) { retval = GATXds_SerialiseObject(GATString_ToGATObject(string), stream, clear_dirty, 0, "uint32 octet string", GATSTRING_VERSION1, string->byteArray, string->lengthInBytes, string->encoding); } return retval; } /** GATString_VersionCallback * * The function GATString_VersionCallback is used as a callback * function during the de-serialisation of a GATString. It should be * provided to test, whether the de-serialised version matches the expected * version. * * @param version The version number, which was de-serialised from the stream. * * @return This function should return GATTrue, if the version matches the * expected value (version is valid), GATFalse otherwise. * * @remark This function is called from the GAT engine, there is no need to * call it directly. */ static GATBool GATString_VersionCallback(GATuint32 version) { GATBool retval = GATFalse; if ((version & ~GATSTRING_MINOR_MASK) <= GATSTRING_LASTVERSION) { retval = GATTrue; } return retval; } /** GATString_DeSerialiseCallback * * The function GATString_DeSerialiseCallback is used as a callback * function during the de-serialisation of a GATString. It should be * provided for the instantiation of the new GATString object based on * the already de-serialised data items. * * @param context The GAT context to be used for object construction. * @param stream The stream interface to use for the serialisation. * @param object The pointer to the variable, which should receive the newly * constructed object. * @param version The version of the saved data read from the input stream. * @param args This parameter is the pointer to the va_list containing * pointers to the already de-serialised data items accordingly to the * format string, provided during the call to the * GATString_DeSerialise function. * * @return An error code. * * @remark This function is called from the GAT engine, there is no need to * call it directly. */ static int GATString_DeSerialiseCallback(GATContext context, GATObject stream, GATObject *object, GATuint32 version, va_list args) { int retval = GAT_FAIL; /* the version was eaten already */ char **byte_array = va_arg(args, char **); GATuint32 *byte_array_size = va_arg(args, GATuint32 *); char const **encoding = va_arg(args, char const **); /* construct the new object */ GATString string = (GATString) malloc(sizeof(struct GATString_S)); if (NULL == string) { retval = GAT_MEMORYFAILURE; } else { string->GATObject__vtable = &GATString__vtable; string->GATSerialisable__vtable = &GATString_ISerialisable__vtable; string->byteArray = *byte_array; string->lengthInBytes = *byte_array_size; strncpy(string->encoding, *encoding, GATSTRING_MAX_ENCODING_LENGTH); /* Ensure encoding is null terminated */ (string->encoding)[GATSTRING_MAX_ENCODING_LENGTH - 1] = '\0'; retval = GAT_SUCCESS; } if (GAT_SUCCESS == retval) { if (NULL != object) { *object = GATString_ToGATObject(string); } else { GATString_Destroy(&string); retval = GAT_INVALID_PARAMETER; } } return retval; } /** 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) { GATObject string = NULL; /* the new object will be created here */ /* we must provide all instance data items to be de-serialised for this GATFile object accordingly to the provided format string */ GATuint32 version = 0; char *byte_array = NULL; GATuint32 byte_array_size = 0; char *encoding = NULL; /* read the data */ int retval = GATXds_DeSerialiseObject(context, stream, GATString_DeSerialiseCallback, GATString_VersionCallback, &string, "uint32 octet string", &version, &byte_array, &byte_array_size, &encoding); /* on success the ownership of the byte array was transferred to the new object */ if (GAT_SUCCESS != retval) { free(byte_array); } free(encoding); /* FIXME: GATStatus(retval); */ return GATObject_ToGATString(string); } /** 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. */ int GATString_GetIsDirty(GATString_const string, GATBool *isdirty) { int retval = GAT_INVALID_HANDLE; if (NULL != string) { if (NULL != isdirty) { *isdirty = GATFalse; /* GATString's are never dirty */ retval = GAT_SUCCESS; } else { retval = GAT_INVALID_PARAMETER; } } return retval; }