Vi18nGetExpansionFactor


The Vi18nGetExpansionFactor function calculates the string expansion factor when converting characters from one character set to another.


Syntax

Vi18nError Vi18nGetExpansionFactor(
                                  char *srcCSet,
char *desCSet,
int *expFactor)

Arguments

 


srcCSet

char*   A pointer to the source character set name.

desCSet

char*   A pointer to the destination character set name.

expFactor

int*   The expansion factor.


Returns

This function returns one of the following error codes:

Vi18nSuccess for success

 

Vi18nError_* for an error code identified in Error Codes

 

Vi18nFail for a non-specific error

 


Discussion

You typically call the Vi18nGetExpansionFactor function to determine the allocation of memory for the output buffer used by the Vi18nConvert function.

The expansion factor is a value between 1 and 6. The Vi18nGetExpansionFactor function calculates the largest difference in character lengths between the source character set and the destination character set and returns the value in the expFactor argument, as shown by the following equation:

expFactor = floor(maxCharSize(desCSet) / minCharSize (srcCSet), 1)

where minCharSize and maxCharSize determine the minimum and maximum character sizes in a character set, respectively.

If the size of the smallest char in the source character set is larger than the largest char in the destination characters set, the expansion factor is 1.

For example, if the largest size difference occurs when mapping a 1-byte char in the source character set to a 3-byte char in the destination character set, the expansion factor is 3. If the largest size difference occurs when mapping a 3-byte char in the source character set to a 2-byte char in the destination character set, the expansion factor is 1.

The character set name is case insensitive and common variations are allowed; for example, you can use 8859-1 for iso8859-1 or ISO-8859-1. (For the list of character set names, see Charset Name Mapping Table.)


Example

typedef struct _VgwAppSession {
  VdkStructHeader;            /* Initialize with VdkStructInit */
  VdkCString pszIntCharSet;  /* internal vdk/collection charset */
  VdkCString pszReposCharSet; /* repository charset */
  VdkUint2   nReposCharSet;   /* repository charset enum value */
  VdkUint1   nEndian;         /* repository unicode endian */
  VdkInt4   nRtoIFactor;/* repository to internal charsetfactor */
  VdkVoidp   vi18nContext;    /* vi18n library handle */
} VgwAppSessionRec;

static VdkError
VDK_CALLBACK VgwSessionNew(VgwSessionNewArg pNewArg,
VgwAppSession* ppSession)
{
  VdkError error = VdkSuccess;
  Vi18nError err;
  VgwAppSession pVSes = NULL;
...
/*********************************************************
* get VDK internal charset, i.e. collection charset here
*********************************************************/
if( (pNewArg->vdkver >= VDK_4X_RELEASE) && pNewArg->charSetName
  && !(pVSes->pszIntCharSet = HeapStrcpy(pNewArg->charSetName)) ){
error = VdkError_OutOfMemory;
goto abort;
}
/ ****************************************************************** get repository charset from repository or config files here
*****************************************************************/
if (VdkSuccess != (error =
vgwsamp_getReposCharset(pVSes, &pVSes->pszReposCharSet,
                                   &pVSes->nEndian)))
goto abort;

/****************************************************
 * check i18n information and set pVSes->nRtoIFactor
 ****************************************************/
if( pVSes->pszReposCharSet && pVSes->pszIntCharSet ){
int n = 0;

    if !(pVSes->nReposCharSet) {
      error = VdkError_InvalidArg;
      goto abort;
}

if (Vi18nSuccess != (err =
Vi18nGetExpansionFactor((char*)pVSes->pszReposCharSet,
(char*)pVSes->pszIntCharSet, &n))) {
error = VdkError_FatalError;
      goto abort;
}
pVSes->nRtoIFactor = n;
}
...
}

VdkError
vgwsamp_getReposCharset(VgwAppSession pVSes,
VdkCString* ppszCharSet, VdkUint1* pnEndian)
{/*freed during SesNew or SesFree using HeapFree*/
if( !ppszCharSet || !pnEndian )
return VdkError_InvalidArgs;
*ppszCharSet = NULL;
/* unicode endian 'unicodeEndian', 0 for little endian, 1 for */
/* big endian. Required when either the source or the         */
/* destination charset is UNICODE.                            */
#ifdef _WINDOWS
*pnEndian = 0;
#else
*pnEndian = 1;
#endif
if (!pVSes)
return VdkError_InvalidArgs;
/*****************************************************************
* sample gateway assumes repository document is in UTF-8 charset
*****************************************************************/
if( !(*ppszCharSet = HeapStrcpy(VGW_REPOS_CHARSET)) )
return VdkError_OutOfMemory;

return VdkSuccess;
}