Character set conversion functions
Low Level Decoding

Helper functions to convert between Closed Caption, Teletext, Unicode and the locale character set. More...

## Macros

#define | VBI_NUL_TERMINATED -1

## Functions

unsigned long | vbi_strlen_ucs2 (const uint16_t *src)
char * | vbi_strndup_iconv_ucs2 (const char *dst_codeset, const uint16_t *src, long src_length, int repl_char)
char * | vbi_strndup_iconv (const char *dst_codeset, const char *src_codeset, const char *src, unsigned long src_size, int repl_char)
vbi_bool | vbi_fputs_iconv (FILE *fp, const char *dst_codeset, const char *src_codeset, const char *src, unsigned long src_size, int repl_char)
vbi_bool | vbi_fputs_iconv_ucs2 (FILE *fp, const char *dst_codeset, const uint16_t *src, long src_length, int repl_char)
const char * | vbi_locale_codeset (void)
char * | vbi_strndup_iconv_caption (const char *dst_codeset, const char *src, long src_length, int repl_char) _vbi_alloc
unsigned int | vbi_caption_unicode (unsigned int c, vbi_bool to_upper)

## Detailed Description

Helper functions to convert between Closed Caption, Teletext, Unicode and the locale character set.

## Function Documentation

## vbi_strlen_ucs2()

unsigned long vbi_strlen_ucs2 | ( | const uint16_t * | src | ) |

Parameters

  src | NUL-terminated UCS-2 string.

Counts the characters in the string, up to and excluding the terminating NUL.

Since
  0.2.23

Referenced by vbi_fputs_iconv_ucs2().

## vbi_strndup_iconv_ucs2()

char * vbi_strndup_iconv_ucs2 | ( | const char * | dst_codeset,
|  | const uint16_t * | src,
|  | long | src_length,
|  | int | repl_char )

Parameters

  dst_codeset | Character set name for iconv() conversion, for example "ISO-8859-1". When `NULL` the default is UTF-8.
  src | Source string in UCS-2 format, can be `NULL`.
  src_length | Number of characters (not bytes) in the source string. Can be -1 if the string is NUL terminated.
  repl_char | UCS-2 replacement for characters which are not representable in dst_codeset. When zero the function will fail if the source buffer contains unrepresentable characters.

Converts a UCS-2 string with iconv() and writes the result with a terminating NUL character into a newly allocated buffer.

Returns
  A pointer to the allocated buffer. You must free() the buffer when it is no longer needed. The function returns `NULL` when the conversion fails, when it runs out of memory, src_length is set to zero, or when src is `NULL`.

Since
  0.2.23

## vbi_strndup_iconv()

char * vbi_strndup_iconv | ( | const char * | dst_codeset,
|  | const char * | src_codeset,
|  | const char * | src,
|  | unsigned long | src_size,
|  | int | repl_char )

Parameters

  dst_codeset | Character set name for iconv() conversion, for example "ISO-8859-1". When `NULL` the default is UTF-8.
  src_codeset | Character set name for iconv() conversion, for example "ISO-8859-1". When `NULL` the default is UTF-8.
  src | Source buffer, can be `NULL`.
  src_size | Number of bytes in the source string (excluding the terminating NUL, if any).
  repl_char | UCS-2 replacement for characters which are not representable in dst_codeset. When zero the function will fail if the source buffer contains unrepresentable characters.

Converts a string with iconv() and writes the result with a terminating NUL character into a newly allocated buffer.

Returns
  A pointer to the allocated buffer. You must free() the buffer when it is no longer needed. The function returns `NULL` when the conversion fails, when it runs out of memory or when src is `NULL`.

Since
  0.2.23

Examples
  examples/network.c.

Referenced by vbi_strndup_iconv_caption().

## vbi_fputs_iconv()

vbi_bool vbi_fputs_iconv | ( | FILE * | fp,
|  | const char * | dst_codeset,
|  | const char * | src_codeset,
|  | const char * | src,
|  | unsigned long | src_size,
|  | int | repl_char )

Parameters

  fp | Output file.
  dst_codeset | Character set name for iconv() conversion, for example "ISO-8859-1". When `NULL` the default is UTF-8.
  src_codeset | Character set name for iconv() conversion, for example "ISO-8859-1". When `NULL` the default is UTF-8.
  src | Source buffer, can be `NULL`.
  src_size | Number of bytes in the source string (excluding the terminating NUL, if any).
  repl_char | UCS-2 replacement for characters which are not representable in dst_codeset. When zero the function will fail if the source buffer contains unrepresentable characters.

Converts a string with iconv() and writes the result into the given file.

Returns
  FALSE on failure.

Since
  0.2.23

Referenced by vbi_fputs_iconv_ucs2().

## vbi_fputs_iconv_ucs2()

vbi_bool vbi_fputs_iconv_ucs2 | ( | FILE * | fp,
|  | const char * | dst_codeset,
|  | const uint16_t * | src,
|  | long | src_length,
|  | int | repl_char )

Parameters

  fp | Output file.
  dst_codeset | Character set name for iconv() conversion, for example "ISO-8859-1". When `NULL` the default is UTF-8.
  src | Source string in UCS-2 format, can be `NULL`.
  src_length | Number of characters (not bytes) in the source string. Can be -1 if the string is NUL terminated.
  repl_char | UCS-2 replacement for characters which are not representable in dst_codeset. When zero the function will fail if the source buffer contains unrepresentable characters.

Converts a UCS-2 string with iconv() and writes the result into the given file.

Returns
  FALSE on failure.

Since
  0.2.23

References vbi_fputs_iconv(), and vbi_strlen_ucs2().

## vbi_locale_codeset()

const char * vbi_locale_codeset | ( | void |  | ) |

Returns the character encoding used by the current locale, for example "UTF-8". `NULL` if unknown.

Note applications must call

setlocale (LC_ALL, "");

to use the locale specified by the environment. The default C locale uses ASCII encoding.

Since
  0.2.23

Examples
  examples/network.c.

## vbi_strndup_iconv_caption()

char * vbi_strndup_iconv_caption | ( | const char * | dst_codeset,
|  | const char * | src,
|  | long | src_length,
|  | int | repl_char )

extern

Parameters

  dst_codeset | Character set name for iconv() conversion, for example "ISO-8859-1". When `NULL` the default is UTF-8.
  src | String of Closed Caption characters, can be `NULL`.
  src_length | Number of characters (= bytes) in the source string. Can be -1 if the src string is NUL terminated.
  repl_char | UCS-2 replacement for characters which are not representable in dst_codeset. When zero the function will fail if the source buffer contains unrepresentable characters.

Converts a string of EIA 608 Closed Caption characters to another format and stores the result with a terminating NUL in a newly allocated buffer. The function ignores parity bits and the bytes 0x00 ... 0x1F except two byte special and extended characters (e.g. music note 0x11 0x37).

See also
  vbi_caption_unicode()

Returns
  A pointer to the allocated buffer. You must free() the buffer when it is no longer needed. The function returns `NULL` when the source buffer contains invalid two byte characters, when the conversion fails, when it runs out of memory or when src is `NULL`.

Since
  0.2.23

References vbi_strndup_iconv().

## vbi_caption_unicode()

unsigned int vbi_caption_unicode | ( | unsigned int | c,
|  | vbi_bool | to_upper )

Parameters

  c | Character code in range 0x20 ... 0x7F, 0x1130 ... 0x113F, 0x1930 ... 0x193F, 0x1220 ... 0x123F, 0x1A20 ... 0x1A3F, 0x1320 ... 0x133F, 0x1B20 ... 0x1B3F.
  to_upper | Convert the character to upper case. (In general real time caption is capitalized, but for a few accented characters older versions of the standard defined only lower case character codes. This option is available to conveniently capitalize all characters received.)

Converts a Closed Caption character code to Unicode. Codes in range 0x1130 to 0x1B3F are "special characters" and "extended characters" (e.g. caption command 0x11 0x37).

See also
  vbi_strndup_iconv_caption()

Returns
  Unicode value or 0 if c is outside the valid ranges.

Since
  0.2.23