locn2utf8

Converts a string from the local code page to UTF-8.

Library:LibC
Service:Characters and Strings

Syntax

  #include <unilib.h> 
   
  int locn2utf8 (
     UniRuleTable_t   table,
     char            *dest,
     size_t          *destLen,
     const char      *src,
     size_t           srcLen,
     char             noMapCh,
     int              noMapFlag);

Parameters

table

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

dest

(OUT) Points to the converted string.

destLen

(IN/OUT) Points to the maximum number of bytes that the converted string can contain. On return, points to the number of bytes in the converted string.

src

(IN) Points to the source string in local code page format.

srcLen

(IN) Specifies the number of bytes in the source string.

noMapCh

(IN) Specifies an arbitrary character to be used in place of a source character for which no mapping can be found in the table. The noMapFlag parameter determines whether this character is used.

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.

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.

-506

UNI_ERR_PREMATURE_END

The string ended prematurely. This error can occur only in translating from a string in the local code page into UTF-8.

-532

UNI_ERR_UNMAPPABLE_CHAR

A character in the source is unmappable.

Remarks

For sample code, see UniLib.c.

See Also