Utf8ToLocSize

Computes the number of bytes that must be allocated to convert a string from UTF-8 to the local code page.

Library:LibC
Service:Characters and Strings

Syntax

  #include <unilib.h> 
   
  int Utf8ToLocSize (
     UniRuleTable_t   table,
     const char      *str,
     size_t           unmappedCharSize,
     int              noMapFlag,
     size_t          *locBufSize);

Parameters

table

(IN) Specifies the table to use for the conversion. To use the host's default code page, specify UNI_LOCAL_DEFAULT. Otherwise, specify the value returned from the UniGetTable function.

str

(IN) Points to the source string.

unmappedCharSize

(IN) Specifies, in bytes, the maximum size of the character that is used if an unmappable character is encountered. For example, if your longest special sequence for an unmappable character is [0x015F], you would set this parameter to 8 * sizeof(char).

An unmappable character sequence must be a sequence that does not exist in the target local code page. Because you select this sequence, you must specify how long it is.

noMapFlag

(IN) Specifies whether to replace an unmappable character or simply return an error. It uses one of the following flags:

Flag

Value

Description

UNI_MAP_NO_CHAR

0

Returns the UNI_ERR_UNMAPPABLE_CHAR error code as soon as a character is found to be unmappable. The result is null-terminated at the offending position in the string.

UNI_MAP_CHAR

1

Uses the value in noMapCh for all unmappable characters.

UNI_MAP_SELF

2

Uses the source character. In many cases this does not result in anything useful.
locBufSize

(IN) Points to the number of bytes required for the string in local code page, minus the null terminator.

Return Values

If successful, returns 0. Otherwise, returns a negative error code:

Decimal

Name

Description

-496

UNI_ERR_BAD_HANDLE

The table parameter specifies a nonexistent rule table.

-532

UNI_ERR_UNMAPPABLE_CHAR

A character in the source is unmappable.

Remarks

An application usually employs strings with adequate extra room to prevent memory overwrites, just as an application only rarely measures an ASCII string with strlen to find out how much room to provide for dest in strcpy (dest, src). However, when the resulting length of destination strings is in question because of wildly unpredictable source strings, this function, its companions with “Size” in their names, and the functions with a dryRunSize argument can completely prevent memory overwrites.

See Also

LocToUtf8Size