Intel® Fortran Compiler Classic and Intel® Fortran Compiler Developer Guide and Reference

ID 767251
Date 3/22/2024
Public
Document Table of Contents

MBConvertMBToUnicode

NLS Function: Converts a multibyte-character string from the current codepage to a Unicode string. This routine is only available for Windows.

Module

USE IFNLS

result = MBConvertMBToUnicode (mbstr,unicodestr[,flags])

mbstr

(Input) Character*(*). Is a multibyte codepage string to be converted.

unicodestr

(Output) INTEGER(2). Is an array of integers that is the translation of the input string into Unicode.

flags

(Input; optional) INTEGER(4). If specified, modifies the string conversion. If flags is omitted, the value NLS$Precomposed is used. Available values (defined in IFNLS.F90) are:

  • NLS$Precomposed - Use precomposed characters always. (default)

  • NLS$Composite - Use composite wide characters always.

  • NLS$UseGlyphChars - Use glyph characters instead of control characters.

  • NLS$ErrorOnInvalidChars - Returns -1 if an invalid input character is encountered.

The flags NLS$Precomposed and NLS$Composite are mutually exclusive. You can combine NLS$UseGlyphChars with either NLS$Precomposed or NLS$Composite using an inclusive OR (IOR or OR).

Results

The result type is INTEGER(4). If no error occurs, the result is the number of bytes written to unicodestr (bytes are counted, not characters), or the number of bytes required to hold the output string if unicodestr has zero size.

If the unicodestr array is bigger than needed to hold the translation, the extra elements are set to space characters. If unicodestr has zero size, the function returns the number of bytes required to hold the translation and nothing is written to unicodestr.

If an error occurs, one of the following negative values is returned:

  • NLS$ErrorInsufficentBuffer - The unicodestr argument is too small, but not zero size so that the needed number of bytes would be returned.

  • NLS$ErrorInvalidFlags - The flags argument has an illegal value.

  • NLS$ErrorInvalidCharacter - A character with no Unicode translation was encountered in mbstr. This error can occur only if the NLS$InvalidCharsError flag was used in flags.

NOTE:

By default, or if flags is set to NLS$Precomposed, the function MBConvertMBToUnicode attempts to translate the multibyte codepage string to a precomposed Unicode string. If a precomposed form does not exist, the function attempts to translate the codepage string to a composite form.