The m17n Library: Code Conversion

# Code Conversion
[SHELL API]

Coding system objects and API for them. More...

## Data Structures
struct | MConverter
| Structure to be used in code conversion. More...
struct | MCodingInfoISO2022
| Structure for a coding system of type MCODING_TYPE_ISO_2022. More...
struct | MCodingInfoUTF
| Structure for extra information about a coding system of type MCODING_TYPE_UTF. More...
## Variables: Symbols representing coding systems
MSymbol | Mcoding_us_ascii
| Symbol for the coding system US-ASCII.
MSymbol | Mcoding_iso_8859_1
| Symbol for the coding system ISO-8859-1.
MSymbol | Mcoding_utf_8
| Symbol for the coding system UTF-8.
MSymbol | Mcoding_utf_8_full
| Symbol for the coding system UTF-8-FULL.
MSymbol | Mcoding_utf_16
| Symbol for the coding system UTF-16.
MSymbol | Mcoding_utf_16be
| Symbol for the coding system UTF-16BE.
MSymbol | Mcoding_utf_16le
| Symbol for the coding system UTF-16LE.
MSymbol | Mcoding_utf_32
| Symbol for the coding system UTF-32.
MSymbol | Mcoding_utf_32be
| Symbol for the coding system UTF-32BE.
MSymbol | Mcoding_utf_32le
| Symbol for the coding system UTF-32LE.
MSymbol | Mcoding_sjis
| Symbol for the coding system SJIS.
## Variables: Parameter keys for mconv_define_coding().
MSymbol | Mtype
MSymbol | Mcharsets
MSymbol | Mflags
MSymbol | Mdesignation
MSymbol | Minvocation
MSymbol | Mcode_unit
MSymbol | Mbom
MSymbol | Mlittle_endian
## Variables: Symbols representing coding system types.
MSymbol | Mutf
MSymbol | Miso_2022
## Variables: Symbols appearing in the value of Mflags parameter.
Symbols that can be a value of the Mflags parameter of a coding system used in an argument to the mconv_define_coding() function (which see).
MSymbol | Mreset_at_eol
MSymbol | Mreset_at_cntl
MSymbol | Meight_bit
MSymbol | Mlong_form
MSymbol | Mdesignation_g0
MSymbol | Mdesignation_g1
MSymbol | Mdesignation_ctext
MSymbol | Mdesignation_ctext_ext
MSymbol | Mlocking_shift
MSymbol | Msingle_shift
MSymbol | Msingle_shift_7
MSymbol | Meuc_tw_shift
MSymbol | Miso_6429
MSymbol | Mrevision_number
MSymbol | Mfull_support
## Variables: Others
Remaining variables.
MSymbol | Mmaybe
| Symbol whose name is "maybe".
MSymbol | Mcoding
| The symbol `Mcoding`.
## Enumerations
enum | MConversionResult { MCONVERSION_RESULT_SUCCESS, MCONVERSION_RESULT_INVALID_BYTE, MCONVERSION_RESULT_INVALID_CHAR, MCONVERSION_RESULT_INSUFFICIENT_SRC, MCONVERSION_RESULT_INSUFFICIENT_DST, MCONVERSION_RESULT_IO_ERROR }
| Codes that represent the result of code conversion. More...
enum | MCodingType { MCODING_TYPE_CHARSET, MCODING_TYPE_UTF, MCODING_TYPE_ISO_2022, MCODING_TYPE_MISC }
| Types of coding system. More...
enum | MCodingFlagISO2022 { MCODING_ISO_RESET_AT_EOL = 0x1, MCODING_ISO_RESET_AT_CNTL = 0x2, MCODING_ISO_EIGHT_BIT = 0x4, MCODING_ISO_LONG_FORM = 0x8, MCODING_ISO_DESIGNATION_G0 = 0x10, MCODING_ISO_DESIGNATION_G1 = 0x20, MCODING_ISO_DESIGNATION_CTEXT = 0x40, MCODING_ISO_DESIGNATION_CTEXT_EXT = 0x80, MCODING_ISO_LOCKING_SHIFT = 0x100, MCODING_ISO_SINGLE_SHIFT = 0x200, MCODING_ISO_SINGLE_SHIFT_7 = 0x400, MCODING_ISO_EUC_TW_SHIFT = 0x800, MCODING_ISO_ISO6429 = 0x1000, MCODING_ISO_REVISION_NUMBER = 0x2000, MCODING_ISO_FULL_SUPPORT = 0x3000, MCODING_ISO_FLAG_MAX }
| Bit-masks to specify the detail of coding system whose type is MCODING_TYPE_ISO_2022. More...
## Functions
MSymbol | mconv_define_coding (const char *name, MPlist *plist, int(*resetter)(MConverter *), int(*decoder)(const unsigned char *, int, MText *, MConverter *), int(*encoder)(MText *, int, int, unsigned char *, int, MConverter *), void *extra_info)
| Define a coding system.
MSymbol | mconv_resolve_coding (MSymbol symbol)
| Resolve coding system name.
int | mconv_list_codings (MSymbol **symbols)
| List symbols representing coding systems.
MConverter * | mconv_buffer_converter (MSymbol name, const unsigned char *buf, int n)
| Create a code converter bound to a buffer.
MConverter * | mconv_stream_converter (MSymbol name, FILE *fp)
| Create a code converter bound to a stream.
int | mconv_reset_converter (MConverter *converter)
| Reset a code converter.
void | mconv_free_converter (MConverter *converter)
| Free a code converter.
MConverter * | mconv_rebind_buffer (MConverter *converter, const unsigned char *buf, int n)
| Bind a buffer to a code converter.
MConverter * | mconv_rebind_stream (MConverter *converter, FILE *fp)
| Bind a stream to a code converter.
MText * | mconv_decode (MConverter *converter, MText *mt)
| Decode a byte sequence into an M-text.
MText * | mconv_decode_buffer (MSymbol name, const unsigned char *buf, int n)
| Decode a buffer area based on a coding system.
MText * | mconv_decode_stream (MSymbol name, FILE *fp)
| Decode a stream input based on a coding system.
int | mconv_encode (MConverter *converter, MText *mt)
| Encode an M-text into a byte sequence.
int | mconv_encode_range (MConverter *converter, MText *mt, int from, int to)
| Encode a part of an M-text.
int | mconv_encode_buffer (MSymbol name, MText *mt, unsigned char *buf, int n)
| Encode an M-text into a buffer area.
int | mconv_encode_stream (MSymbol name, MText *mt, FILE *fp)
| Encode an M-text to write to a stream.
int | mconv_getc (MConverter *converter)
| Read a character via a code converter.
int | mconv_ungetc (MConverter *converter, int c)
| Push a character back to a code converter.
int | mconv_putc (MConverter *converter, int c)
| Write a character via a code converter.
MText * | mconv_gets (MConverter *converter, MText *mt)
| Read a line using a code converter.

## Detailed Description

Coding system objects and API for them.

The m17n library represents a character encoding scheme (CES) of coded character sets (CCS) as an object called coding system. Application programs can add original coding systems.

To encode means converting code-points to character codes and to decode means converting character codes back to code-points.

Application programs can decode a byte sequence with a specified coding system into an M-text, and inversely, can encode an M-text into a byte sequence.

## Enumeration Type Documentation

enum MConversionResult

Codes that represent the result of code conversion.

One of these values is set in `MConverter->result`.

Enumerator:

  MCONVERSION_RESULT_SUCCESS | Code conversion is successful.
  MCONVERSION_RESULT_INVALID_BYTE | On decoding, the source contains an invalid byte.
  MCONVERSION_RESULT_INVALID_CHAR | On encoding, the source contains a character that cannot be encoded by the specified coding system.
  MCONVERSION_RESULT_INSUFFICIENT_SRC | On decoding, the source ends with an incomplete byte sequence.
  MCONVERSION_RESULT_INSUFFICIENT_DST | On encoding, the destination is too short to store the result.
  MCONVERSION_RESULT_IO_ERROR | An I/O error occurred in the conversion.

enum MCodingType

Types of coding system.

Enumerator:

  MCODING_TYPE_CHARSET | A coding system of this type supports charsets directly. The dimension of each charset defines the length of bytes to represent a single character of the charset, and a byte sequence directly represents the code-point of a character. The m17n library provides the default decoding and encoding routines of this type.
  MCODING_TYPE_UTF | A coding system of this type supports byte sequences of a UTF (UTF-8, UTF-16, UTF-32) like structure. The m17n library provides the default decoding and encoding routines of this type.
  MCODING_TYPE_ISO_2022 | A coding system of this type supports byte sequences of an ISO-2022 like structure. The details of each structure are specified by `MCodingInfoISO2022` . The m17n library provides decoding and encoding routines of this type.
  MCODING_TYPE_MISC | A coding system of this type is for byte sequences of miscellaneous structures. The m17n library does not provide decoding and encoding routines of this type. They must be provided by the application program.

enum MCodingFlagISO2022

Bit-masks to specify the detail of coding system whose type is MCODING_TYPE_ISO_2022.

Enumerator:

  MCODING_ISO_RESET_AT_EOL | On encoding, reset the invocation and designation status to initial at end of line.
  MCODING_ISO_RESET_AT_CNTL | On encoding, reset the invocation and designation status to initial before any control codes.
  MCODING_ISO_EIGHT_BIT | Use the right graphic plane.
  MCODING_ISO_LONG_FORM | Use the non-standard 4 bytes format for designation sequence for charsets JISX0208-1978, GB2312, and JISX0208-1983.
  MCODING_ISO_DESIGNATION_G0 | On encoding, unless explicitly specified, designate charsets to G0.
  MCODING_ISO_DESIGNATION_G1 | On encoding, unless explicitly specified, designate charsets except for ASCII to G1.
  MCODING_ISO_DESIGNATION_CTEXT | On encoding, unless explicitly specified, designate 94-chars charsets to G0, 96-chars charsets to G1.
  MCODING_ISO_DESIGNATION_CTEXT_EXT | On encoding, encode such charsets not conforming to ISO-2022 by ESC % / ..., and encode non-supported Unicode characters by ESC % G ... ESC % @ . On decoding, handle those escape sequences.
  MCODING_ISO_LOCKING_SHIFT | Use locking shift.
  MCODING_ISO_SINGLE_SHIFT | Use single shift (SS2 (0x8E or ESC N), SS3 (0x8F or ESC O)).
  MCODING_ISO_SINGLE_SHIFT_7 | Use 7-bit single shift 2 (SS2 (0x19)).
  MCODING_ISO_EUC_TW_SHIFT | Use EUC-TW like special shifting.
  MCODING_ISO_ISO6429 | Use ISO-6429 escape sequences to indicate direction. Not yet implemented.
  MCODING_ISO_REVISION_NUMBER | On encoding, if a charset has revision number, produce escape sequences to specify the number.
  MCODING_ISO_FULL_SUPPORT | Support all ISO-2022 charsets.
  MCODING_ISO_FLAG_MAX |

## Function Documentation

MSymbol mconv_define_coding | ( | const char * | name,
|  | MPlist * | plist,
|  | int(*)(MConverter *) | resetter,
|  | int(*)(const unsigned char *, int, MText *, MConverter *) | decoder,
|  | int(*)(MText *, int, int, unsigned char *, int, MConverter *) | encoder,
|  | void * | extra_info |
| ) |  |  |

Define a coding system.

The mconv_define_coding() function defines a new coding system and makes it accessible via a symbol whose name is name. plist specifies parameters of the coding system as below:

- Key is `Mtype`, value is a symbol

  The value specifies the type of the coding system. It must be Mcharset, Mutf, Miso_2022, or Mnil.

  If the type is Mcharset, extra_info is ignored.

  If the type is Mutf, extra_info must be a pointer to MCodingInfoUTF.

  If the type is Miso_2022, extra_info must be a pointer to MCodingInfoISO2022.

  If the type is Mnil, the argument resetter, decoder, and encoder must be supplied. extra_info is ignored. Otherwise, they can be `NULL` and the m17n library provides proper defaults.

- Key is Mcharsets, value is a plist

  The value specifies a list charsets supported by the coding system. The keys of the plist must be Msymbol, and the values must be symbols representing charsets.

- Key is Mflags, value is a plist

  If the type is Miso_2022, the values specifies flags to control the ISO 2022 interpreter. The keys of the plist must e Msymbol, and values must be one of the following.

  - Mreset_at_eol

    If this flag exists, designation and invocation status is reset to the initial state at the end of line.

  - Mreset_at_cntl

    If this flag exists, designation and invocation status is reset to the initial state at a control character.

  - Meight_bit

    If this flag exists, the graphic plane right is used.

  - Mlong_form

    If this flag exists, the over-long escape sequences (ESC '$' '(' <final_byte>) are used for designating the CCS JISX0208.1978, GB2312, and JISX0208.

  - Mdesignation_g0

    If this flag and Mfull_support exists, designates charsets not listed in the charset list to the graphic register G0.

  - Mdesignation_g1

    If this flag and Mfull_support exists, designates charsets not listed in the charset list to the graphic register G1.

  - Mdesignation_ctext

    If this flag and Mfull_support exists, designates charsets not listed in the charset list to a graphic register G0 or G1 based on the criteria of the Compound Text.

  - Mdesignation_ctext_ext

    If this flag and Mfull_support exists, designates charsets not listed in the charset list to a graphic register G0 or G1, or use extended segment for such charsets based on the criteria of the Compound Text.

  - Mlocking_shift

    If this flag exists, use locking shift.

  - Msingle_shift

    If this flag exists, use single shift.

  - Msingle_shift_7

    If this flag exists, use 7-bit single shift code (0x19).

  - Meuc_tw_shift

    If this flag exists, use a special shifting according to EUC-TW.

  - Miso_6429

    This flag is currently ignored.

  - Mrevision_number

    If this flag exists, use a revision number escape sequence to designate a charset that has a revision number.

  - Mfull_support

    If this flag exists, support all charsets registered in the International Registry.

- Key is Mdesignation, value is a plist

  If the type is Miso_2022, the value specifies how to designate each supported characters. The keys of the plist must be Minteger, and the values must be numbers indicating a graphic registers. The Nth element value is for the Nth charset of the charset list. The value 0..3 means that it is assumed that a charset is already designated to the graphic register 0..3. The negative value G (-4..-1) means that a charset is not designated to any register at first, and if necessary, is designated to the (G+4) graphic register.

- Key is Minvocation, value is a plist

  If the type is Miso_2022, the value specifies how to invocate each graphic registers. The plist length must be one or two. The keys of the plist must be Minteger, and the values must be numbers indicating a graphic register. The value of the first element specifies which graphic register is invocated to the graphic plane left. If the length is one, no graphic register is invocated to the graphic plane right. Otherwise, the value of the second element specifies which graphic register is invocated to the graphic plane right.

- Key is Mcode_unit, value is an integer

  If the type is Mutf, the value specifies the bit length of a code-unit. It must be 8, 16, or 32.

- Key is Mbom, value is a symbol

  If the type is Mutf and the code-unit bit length is 16 or 32, it specifies whether or not to use BOM (Byte Order Mark). If the value is Mnil (default), BOM is not used, else if the value is Mmaybe, the existence of BOM is detected at decoding time, else BOM is used.

- Key is Mlittle_endian, value is a symbol

  If the type is Mutf and the code-unit bit length is 16 or 32, it specifies whether or not the encoding is little endian. If the value is Mnil (default), it is big endian, else it is little endian.

resetter is a pointer to a function that resets a converter for the coding system to the initial status. The pointed function is called with one argument, a pointer to a converter object.

decoder is a pointer to a function that decodes a byte sequence according to the coding system. The pointed function is called with four arguments:

- A pointer to the byte sequence to decode.
- The number of bytes to decode.
- A pointer to an M-text to which the decoded characters are appended.
- A pointer to a converter object.

decoder must return 0 if it succeeds. Otherwise it must return -1.

encoder is a pointer to a function that encodes an M-text according to the coding system. The pointed function is called with six arguments:

- A pointer to the M-text to encode.
- The starting position of the encoding.
- The ending position of the encoding.
- A pointer to a memory area where the produced bytes are stored.
- The size of the memory area.
- A pointer to a converter object.

encoder must return 0 if it succeeds. Otherwise it must return -1.

extra_info is a pointer to a data structure that contains extra information about the coding system. The type of the data structure depends on type.

Return value:

If the operation was successful, mconv_define_coding() returns a symbol whose name is name. If an error is detected, it returns Mnil and assigns an error code to the external variable merror_code.

Errors:
  `MERROR_CODING`

MSymbol mconv_resolve_coding | ( | MSymbol | symbol | ) |

Resolve coding system name.

The mconv_resolve_coding() function returns symbol if it represents a coding system. Otherwise, canonicalize symbol as to a coding system name, and if the canonicalized name represents a coding system, return it. Otherwise, return Mnil.

int mconv_list_codings | ( | MSymbol ** | symbols | ) |

List symbols representing coding systems.

The mconv_list_codings() function makes an array of symbols representing a coding system, stores the pointer to the array in a place pointed to by symbols, and returns the length of the array.

MConverter* mconv_buffer_converter | ( | MSymbol | name,
|  | const unsigned char * | buf,
|  | int | n |
| ) |  |  |

Create a code converter bound to a buffer.

The mconv_buffer_converter() function creates a pointer to a code converter for coding system name. The code converter is bound to buffer area of n bytes pointed to by buf. Subsequent decodings and encodings are done to/from this buffer area.

name can be Mnil. In this case, a coding system associated with the current locale (LC_CTYPE) is used.

Return value:
  If the operation was successful, mconv_buffer_converter() returns the created code converter. Otherwise it returns `NULL` and assigns an error code to the external variable merror_code.

Errors:
  `MERROR_SYMBOL`, `MERROR_CODING`

See Also:
  mconv_stream_converter()

MConverter* mconv_stream_converter | ( | MSymbol | name,
|  | FILE * | fp |
| ) |  |  |

Create a code converter bound to a stream.

The mconv_stream_converter() function creates a pointer to a code converter for coding system name. The code converter is bound to stream fp. Subsequent decodings and encodings are done to/from this stream.

name can be Mnil. In this case, a coding system associated with the current locale (LC_CTYPE) is used.

Return value:
  If the operation was successful, mconv_stream_converter() returns the created code converter. Otherwise it returns `NULL` and assigns an error code to the external variable merror_code.

Errors:
  `MERROR_SYMBOL`, `MERROR_CODING`

See Also:
  mconv_buffer_converter()

int mconv_reset_converter | ( | MConverter * | converter | ) |

Reset a code converter.

The mconv_reset_converter() function resets code converter converter to the initial state.

Return value:
  If converter->coding has its own reseter function, mconv_reset_converter() returns the result of that function applied to converter. Otherwise it returns 0.

void mconv_free_converter | ( | MConverter * | converter | ) |

Free a code converter.

The mconv_free_converter() function frees the code converter converter.

MConverter* mconv_rebind_buffer | ( | MConverter * | converter,
|  | const unsigned char * | buf,
|  | int | n |
| ) |  |  |

Bind a buffer to a code converter.

The mconv_rebind_buffer() function binds buffer area of n bytes pointed to by buf to code converter converter. Subsequent decodings and encodings are done to/from this newly bound buffer area.

Return value:
  This function always returns converter.

See Also:
  mconv_rebind_stream()

MConverter* mconv_rebind_stream | ( | MConverter * | converter,
|  | FILE * | fp |
| ) |  |  |

Bind a stream to a code converter.

The mconv_rebind_stream() function binds stream fp to code converter converter. Following decodings and encodings are done to/from this newly bound stream.

Return value:
  This function always returns converter.

See Also:
  mconv_rebind_buffer()

MText* mconv_decode | ( | MConverter * | converter,
|  | MText * | mt |
| ) |  |  |

Decode a byte sequence into an M-text.

The mconv_decode() function decodes a byte sequence and appends the result at the end of M-text mt. The source byte sequence is taken from either the buffer area or the stream that is currently bound to converter.

Return value:
  If the operation was successful, mconv_decode() returns updated mt. Otherwise it returns `NULL` and assigns an error code to the external variable merror_code.

Errors:
  `MERROR_IO`, `MERROR_CODING`

See Also:
  mconv_rebind_buffer(), mconv_rebind_stream(), mconv_encode(), mconv_encode_range(), mconv_decode_buffer(), mconv_decode_stream()

MText* mconv_decode_buffer | ( | MSymbol | name,
|  | const unsigned char * | buf,
|  | int | n |
| ) |  |  |

Decode a buffer area based on a coding system.

The mconv_decode_buffer() function decodes n bytes of the buffer area pointed to by buf based on the coding system name. A temporary code converter for decoding is automatically created and freed.

Return value:
  If the operation was successful, mconv_decode_buffer() returns the resulting M-text. Otherwise it returns `NULL` and assigns an error code to the external variable merror_code.

Errors:
  `MERROR_IO`, `MERROR_CODING`

See Also:
  mconv_decode(), mconv_decode_stream()

MText* mconv_decode_stream | ( | MSymbol | name,
|  | FILE * | fp |
| ) |  |  |

Decode a stream input based on a coding system.

The mconv_decode_stream() function decodes the entire byte sequence read in from stream fp based on the coding system name. A code converter for decoding is automatically created and freed.

Return value:
  If the operation was successful, mconv_decode_stream() returns the resulting M-text. Otherwise it returns `NULL` and assigns an error code to the external variable merror_code.

Errors:
  `MERROR_IO`, `MERROR_CODING`

See Also:
  mconv_decode(), mconv_decode_buffer()

int mconv_encode | ( | MConverter * | converter,
|  | MText * | mt |
| ) |  |  |

Encode an M-text into a byte sequence.

The mconv_encode() function encodes M-text mt and writes the resulting byte sequence into the buffer area or the stream that is currently bound to code converter converter.

Return value:
  If the operation was successful, mconv_encode() returns the number of written bytes. Otherwise it returns -1 and assigns an error code to the external variable merror_code.

Errors:
  `MERROR_IO`, `MERROR_CODING`

See Also:
  mconv_rebind_buffer(), mconv_rebind_stream(), mconv_decode(), mconv_encode_range()

int mconv_encode_range | ( | MConverter * | converter,
|  | MText * | mt,
|  | int | from,
|  | int | to |
| ) |  |  |

Encode a part of an M-text.

The mconv_encode_range() function encodes the text between from (inclusive) and to (exclusive) in M-text mt and writes the resulting byte sequence into the buffer area or the stream that is currently bound to code converter converter.

Return value:
  If the operation was successful, mconv_encode_range() returns the number of written bytes. Otherwise it returns -1 and assigns an error code to the external variable merror_code.

Errors:
  `MERROR_RANGE`, `MERROR_IO`, `MERROR_CODING`

See Also:
  mconv_rebind_buffer(), mconv_rebind_stream(), mconv_decode(), mconv_encode()

int mconv_encode_buffer | ( | MSymbol | name,
|  | MText * | mt,
|  | unsigned char * | buf,
|  | int | n |
| ) |  |  |

Encode an M-text into a buffer area.

The mconv_encode_buffer() function encodes M-text mt based on coding system name and writes the resulting byte sequence into the buffer area pointed to by buf. At most n bytes are written. A temporary code converter for encoding is automatically created and freed.

Return value:
  If the operation was successful, mconv_encode_buffer() returns the number of written bytes. Otherwise it returns -1 and assigns an error code to the external variable merror_code.

Errors:
  `MERROR_IO`, `MERROR_CODING`

See Also:
  mconv_encode(), mconv_encode_stream()

int mconv_encode_stream | ( | MSymbol | name,
|  | MText * | mt,
|  | FILE * | fp |
| ) |  |  |

Encode an M-text to write to a stream.

The mconv_encode_stream() function encodes M-text mt based on coding system name and writes the resulting byte sequence to stream fp. A temporary code converter for encoding is automatically created and freed.

Return value:
  If the operation was successful, mconv_encode_stream() returns the number of written bytes. Otherwise it returns -1 and assigns an error code to the external variable merror_code.

Errors:
  `MERROR_IO`, `MERROR_CODING`

See Also:
  mconv_encode(), mconv_encode_buffer(), mconv_encode_file()

int mconv_getc | ( | MConverter * | converter | ) |

Read a character via a code converter.

The mconv_getc() function reads one character from the buffer area or the stream that is currently bound to code converter converter. The decoder of converter is used to decode the byte sequence. The internal status of converter is updated appropriately.

Return value:
  If the operation was successful, mconv_getc() returns the character read in. If the input source reaches EOF, it returns `EOF` without changing the external variable merror_code. If an error is detected, it returns `EOF` and assigns an error code to merror_code.

Errors:
  `MERROR_CODING`

See Also:
  mconv_ungetc(), mconv_putc(), mconv_gets()

int mconv_ungetc | ( | MConverter * | converter,
|  | int | c |
| ) |  |  |

Push a character back to a code converter.

The mconv_ungetc() function pushes character c back to code converter converter. Any number of characters can be pushed back. The lastly pushed back character is firstly read by the subsequent mconv_getc() call. The characters pushed back are registered only in converter; they are not written to the input source. The internal status of converter is updated appropriately.

Return value:
  If the operation was successful, mconv_ungetc() returns c. Otherwise it returns `EOF` and assigns an error code to the external variable merror_code.

Errors:
  `MERROR_CODING`, `MERROR_CHAR`

See Also:
  mconv_getc(), mconv_putc(), mconv_gets()

int mconv_putc | ( | MConverter * | converter,
|  | int | c |
| ) |  |  |

Write a character via a code converter.

The mconv_putc() function writes character c to the buffer area or the stream that is currently bound to code converter converter. The encoder of converter is used to encode the character. The number of bytes actually written is set to the `nbytes` member of converter. The internal status of converter is updated appropriately.

Return value:
  If the operation was successful, mconv_putc() returns c. If an error is detected, it returns `EOF` and assigns an error code to the external variable merror_code.

Errors:
  `MERROR_CODING`, `MERROR_IO`, `MERROR_CHAR`

See Also:
  mconv_getc(), mconv_ungetc(), mconv_gets()

MText* mconv_gets | ( | MConverter * | converter,
|  | MText * | mt |
| ) |  |  |

Read a line using a code converter.

The mconv_gets() function reads one line from the buffer area or the stream that is currently bound to code converter converter. The decoder of converter is used for decoding. The decoded character sequence is appended at the end of M-text mt. The final newline character in the original byte sequence is not appended. The internal status of converter is updated appropriately.

Return value:
  If the operation was successful, mconv_gets() returns the modified mt. If it encounters EOF without reading a single character, it returns mt without changing it. If an error is detected, it returns `NULL` and assigns an error code to merror_code.

Errors:
  `MERROR_CODING`

See Also:
  mconv_getc(), mconv_ungetc(), mconv_putc()

## Variable Documentation

MSymbol Mcoding_us_ascii

Symbol for the coding system US-ASCII.

The symbol Mcoding_us_ascii has name `"us-ascii"` and represents a coding system for the CES US-ASCII.

MSymbol Mcoding_iso_8859_1

Symbol for the coding system ISO-8859-1.

The symbol Mcoding_iso_8859_1 has name `"iso-8859-1"` and represents a coding system for the CES ISO-8859-1.

MSymbol Mcoding_utf_8

Symbol for the coding system UTF-8.

The symbol Mcoding_utf_8 has name `"utf-8"` and represents a coding system for the CES UTF-8.

MSymbol Mcoding_utf_8_full

Symbol for the coding system UTF-8-FULL.

The symbol Mcoding_utf_8_full has name `"utf-8-full"` and represents a coding system that is a extension of UTF-8. This coding system uses the same encoding algorithm as UTF-8 but is not limited to the Unicode characters. It can encode all characters supported by the m17n library.

MSymbol Mcoding_utf_16

Symbol for the coding system UTF-16.

The symbol Mcoding_utf_16 has name `"utf-16"` and represents a coding system for the CES UTF-16 (RFC 2279).

MSymbol Mcoding_utf_16be

Symbol for the coding system UTF-16BE.

The symbol Mcoding_utf_16be has name `"utf-16be"` and represents a coding system for the CES UTF-16BE (RFC 2279).

MSymbol Mcoding_utf_16le

Symbol for the coding system UTF-16LE.

The symbol Mcoding_utf_16le has name `"utf-16le"` and represents a coding system for the CES UTF-16LE (RFC 2279).

MSymbol Mcoding_utf_32

Symbol for the coding system UTF-32.

The symbol Mcoding_utf_32 has name `"utf-32"` and represents a coding system for the CES UTF-32 (RFC 2279).

MSymbol Mcoding_utf_32be

Symbol for the coding system UTF-32BE.

The symbol Mcoding_utf_32be has name `"utf-32be"` and represents a coding system for the CES UTF-32BE (RFC 2279).

MSymbol Mcoding_utf_32le

Symbol for the coding system UTF-32LE.

The symbol Mcoding_utf_32le has name `"utf-32le"` and represents a coding system for the CES UTF-32LE (RFC 2279).

MSymbol Mcoding_sjis

Symbol for the coding system SJIS.

The symbol Mcoding_sjis has name `"sjis"` and represents a coding system for the CES Shift-JIS.

MSymbol Mtype

Parameter key for mconv_define_coding() (which see).

MSymbol Mcharsets

MSymbol Mflags

MSymbol Mdesignation

MSymbol Minvocation

MSymbol Mcode_unit

MSymbol Mbom

MSymbol Mlittle_endian

MSymbol Mutf

Symbol that can be a value of the Mtype parameter of a coding system used in an argument to the mconv_define_coding() function (which see).

MSymbol Miso_2022

MSymbol Mreset_at_eol

MSymbol Mreset_at_cntl

MSymbol Meight_bit

MSymbol Mlong_form

MSymbol Mdesignation_g0

MSymbol Mdesignation_g1

MSymbol Mdesignation_ctext

MSymbol Mdesignation_ctext_ext

MSymbol Mlocking_shift

MSymbol Msingle_shift

MSymbol Msingle_shift_7

MSymbol Meuc_tw_shift

MSymbol Miso_6429

MSymbol Mrevision_number

MSymbol Mfull_support

MSymbol Mmaybe

Symbol whose name is "maybe".

The variable Mmaybe is a symbol of name `"maybe"`. It is used a value of Mbom parameter of the function mconv_define_coding() (which see).

MSymbol Mcoding

The symbol `Mcoding`.

Any decoded M-text has a text property whose key is the predefined symbol `Mcoding`. The name of `Mcoding` is `"coding"`.