m17nConv(3m17n)

📦

version 1.8.4 · 2 versions

1.8.4 · debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
1.6.2 · debian bookworm, ubuntu jammy

, in debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

🌸 NAME 🌸

m17nConv — that's this page, from the m17nConv(3m17n) manual of The m17n Library 💖 — and its full name entry is m17nConv_-_Code_Conver. What it's about: coding system objects and API for them. Periodt. ✨

🎀 SYNOPSIS 🎀

okay so this is the whole cast list before the show even starts. no cap, it's a lot, but every single one of them is important. 🫶

🦋 Data Structures 🦋

struct MConverter — the structure to be used in code conversion. your main character, honestly. 👑
struct MCodingInfoISO2022 — the structure for a coding system of type MCODING_TYPE_ISO_2022.
struct MCodingInfoUTF — the structure for extra information about a coding system of type MCODING_TYPE_UTF.

✨ Enumerations ✨

enum MConversionResult — codes that represent the result of code conversion. the members are:

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
}

enum MCodingType — types of coding system. it's giving taxonomy, it's giving categories:

enum MCodingType {
    MCODING_TYPE_CHARSET,
    MCODING_TYPE_UTF,
    MCODING_TYPE_ISO_2022,
    MCODING_TYPE_MISC
}

enum MCodingFlagISO2022 — bit-masks to specify the detail of coding system whose type is MCODING_TYPE_ISO_2022. bestie, look at these hex values, they ate 💅

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
}

🔥 Functions 🔥

every single one of these, no skipping, that's the rule:

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)
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.

🌈 Variables: Symbols representing coding systems 🌈

these are the icons, the pre-made coding systems, already loaded and ready to slay:

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(). 💜

the little keys you hand over when you're defining your own coding system:

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 🍓

the remaining variables. the stragglers. we love them anyway. 🥺

MSymbol Mmaybe — symbol whose name is 'maybe'.
MSymbol Mcoding — the symbol Mcoding.

👑 Detailed Description 👑

Coding system objects and API for them. That's the vibe, that's the whole thesis. 💖

The m17n library represents a character encoding scheme (CES) of coded character sets (CCS) as an object called a coding system. And here's the fun part bestie — application programs can add original coding systems. yes, you can make your own. iconic behavior. ✨

To encode means converting code-points to character codes, and to decode means converting character codes back to code-points. it's a two-way street, it's giving mutual. 😭

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. that's the whole relationship, no cap. 🦋

💖 Data Structure Documentation 💖

🧚 MConverter 🧚

Structure to be used in code conversion. okay so this is the main character of code conversion structs 💅

✨ FIELD DOCUMENTATION ✨

int MConverter::lenient — set this to nonzero if the conversion should be lenient. By default, conversion is strict (i.e. not lenient).

If strict: the converter stops at the first invalid byte (on decoding) or at the first character not supported by the coding system (on encoding). When that happens, MConverter->result is set to MCONVERSION_RESULT_INVALID_BYTE or MCONVERSION_RESULT_INVALID_CHAR accordingly.

If lenient: on decoding, an invalid byte is kept per se; on encoding, an invalid character is replaced with '<U+XXXX>' (if the character is a Unicode character) or with '<M+XXXXXX>' (otherwise). bestie that's the vibe.

int MConverter::last_block — set to nonzero before decoding or encoding the last block of the byte sequence or the character sequence respectively. The value influences conversion as below.
- On decoding, when the last few bytes are too short to form a valid byte sequence:
  - If nonzero: conversion terminates by error (MCONVERSION_RESULT_INVALID_BYTE) at the first byte of the sequence.
  - If zero: conversion terminates successfully. Those bytes are stored in the converter as carryover and are prepended to the byte sequence of the further conversion.
- On encoding, when the coding system is context dependent:
  - If nonzero: conversion may produce a byte sequence at the end to reset the context to the initial state even if the source characters are zero.
  - If zero: conversion never produce such a byte sequence at the end.
unsigned MConverter::at_most — if nonzero, it specifies at most how many characters to convert.
int MConverter::nchars — the following three members are to report the result of the conversion. Number of characters most recently decoded or encoded.
int MConverter::nbytes — number of bytes recently decoded or encoded.
enum MConversionResult MConverter::result — result code of the conversion.
void* MConverter::ptr — no extra description, just a pointer.
double MConverter::dbl — no extra description, just a double.
char MConverter::c[256] — no extra description, just a 256-char array.
union { ... } MConverter::status — various information about the status of code conversion. The contents depend on the type of coding system. It is assured that status is aligned so that any type of casting is safe and at least 256 bytes of memory space can be used. iykyk
void* MConverter::internal_info — this member is for internally use only. An application program should never touch it. 🙈

🌸 MCodingInfoISO2022 🌸

Structure for a coding system of type MCODING_TYPE_ISO_2022. slay

✨ FIELD DOCUMENTATION ✨

int MCodingInfoISO2022::initial_invocation[2] — table of numbers of an ISO2022 code extension element invoked to each graphic plane (Graphic Left and Graphic Right). -1 means no code extension element is invoked to that plane.
char MCodingInfoISO2022::designations[32] — table of code extension elements. The Nth element corresponds to the Nth charset in charset_names, which is an argument given to the mconv_define_coding() function.
- If an element value is 0..3, it specifies a graphic register number to designate the corresponds charset. In addition, the charset is initially designated to that graphic register.
- If the value is -4..-1, it specifies a graphic register number 0..3 respectively to designate the corresponds charset. Initially, the charset is not designated to any graphic register.
unsigned MCodingInfoISO2022::flags — bitwise OR of enum MCodingFlagISO2022. periodt

🦋 MCodingInfoUTF 🦋

Structure for extra information about a coding system of type MCODING_TYPE_UTF. it's giving UTF energy

✨ FIELD DOCUMENTATION ✨

int MCodingInfoUTF::code_unit_bits — specify bits of a code unit. The value must be 8, 16, or 32.
int MCodingInfoUTF::bom — specify how to handle the heading BOM (byte order mark). The value must be 0, 1, or 2. The meanings are as follows:
- 0: On decoding, check the first two byte. If they are BOM, decide endian by them. If not, decide endian by the member endian. On encoding, produce byte sequence according to endian with heading BOM.
- 1: On decoding, do not handle the first two bytes as BOM, and decide endian by endian. On encoding, produce byte sequence according to endian without BOM.
- 2: On decoding, handle the first two bytes as BOM and decide endian by them. On encoding, produce byte sequence according to endian with heading BOM.

If <code_unit_bits> is 8, the value has no meaning. not me forgetting that

int MCodingInfoUTF::endian — specify the endian type. The value must be 0 or 1. 0 means little endian, and 1 means big endian.

If <code_unit_bits> is 8, the value has no meaning.

🌈 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. we love a success story
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 — no description in the source, just the max flag.

✨ Variable Documentation ✨

Okay bestie, gather round. These are all the global variable symbols the m17n library is serving. Every single one, no cap. 💅

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). 💅

And here's the next clique of symbols, straight from the original with no extra description attached:

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). 🫶

Then this whole squad, also just vibing as symbols in the original:

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). 😭

And finally, the main character herself:

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'. 💖

👑 Author 👑

Generated automatically by Doxygen for The m17n Library from the source code. 💅 (The robots did this one, but we're making it cute.)

💖 COPYRIGHT 💖

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License <http://www.gnu.org/licenses/fdl.html>.

Version 1.8.4, dated Mon Sep 25 2023, from m17nConv(3m17n) — byeee bestie, mwah 💋💖✨

📦 where this page comes from

debian trixie: m17n-docs 1.8.4-1
ubuntu noble: m17n-docs 1.8.4-1
ubuntu questing: m17n-docs 1.8.4-1
ubuntu resolute: m17n-docs 1.8.4-1build1
ubuntu stonking: m17n-docs 1.8.4-1build1
Copyright (C) 2001-2011 National Institute of Advanced Industrial Science and Technology (AIST)
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms