nsIUTF8ConverterService

Method overview

Methods

convertStringToUTF8()

Ensure that aString is encoded in UTF-8. If not, convert to UTF-8 assuming it's encoded in aCharset and return the converted string in UTF-8.

AUTF8String convertStringToUTF8(
  in ACString aString,
  in string aCharset,
  in boolean aSkipCheck,
  in boolean aAllowSubstitution
);

Parameters

aString

A string to ensure its UTF8ness.

aCharset

The charset to convert from if aString is not in UTF-8.

aSkipCheck

Determines whether or not to skip 'ASCIIness' and 'UTF8ness' check. Set this to PR_TRUE only if you suspect that aString can be mistaken for ASCII / UTF-8 but is actually not in ASCII / UTF-8 so that aString has to go through the conversion. Skipping ASCIIness/UTF8ness check. The most common case is the input is in 7bit non-ASCII character sets like ISO-2022-JP, HZ or UTF-7 (in its original form or a modified form used in IMAP folder names).

aAllowSubstitution

when true, allow the decoder to substitute invalid input sequences by replacement characters.

Return value

The converted string in UTF-8.

Exceptions thrown

NS_ERROR_UCONV_NOCONV

When there is no decoder for aCharset or error code of nsIUnicodeDecoder in case of conversion failure.

convertURISpecToUTF8()

Ensure that aSpec (after URL-unescaping it) is encoded in UTF-8. If not, convert it to UTF-8, assuming it's encoded in aCharset, and return the result.

Make sure that all characters outside US-ASCII in your input spec are url-escaped if your spec is not in UTF-8 (before url-escaping) because the presence of non-ASCII characters is blindly regarded as an indication that your input spec is in unescaped UTF-8 and it will be returned without further processing. No valid spec going around in Mozilla code would break this assumption.

AUTF8String convertURISpecToUTF8(
  in ACString aSpec,
  in string aCharset
);

Parameters

aSpec

An url-escaped URI spec to ensure its UTF8ness.

aCharset

The character set to convert from if aSpec is not in UTF-8.

Return value

The converted spec in UTF-8.

Exceptions thrown

NS_ERROR_UCONV_NOCONV

When there is no decoder for aCharset or error code of nsIUnicodeDecoder in case of conversion failure.