PATH Mac OS 8 and 9 Developer Documentation > Text Encoding Conversion Manager
Programming With the Text Encoding Conversion Manager

---

DISCUSSION

The TECConvertText function converts a buffer of text according to information contained in the converter object. The converter object specifies the source encoding, destination encoding, and any intermediate encodings required for conversion. The function returns the text in the output buffer that you provide.

In allocating an output buffer, a good rule of thumb is larger is better, basing your estimate on the byte requirements of the destination encoding. You should always allocate a buffer at least 32 bytes long. For the function to return successfully, the output buffer you allocate must be large enough to accommodate at least part of the converted text. Then, if the function cannot convert all of the text, it executes successfully, returns the portion of the text it converted, and returns the number of source bytes it removed from input in the actualInputLength parameter. You can use this number to identify the next byte to be taken and to determine how many bytes remain. To convert the remaining text, you simply call the function again with the remaining text and a new output buffer.

If the output buffer you allocate is too small to accommodate any of the converted text, the function fails. For example, if the destination encoding requires additional bytes in addition to the actual text (for instance, an escape sequence preceding the converted text), your buffer must be large enough to accommodate both.

IMPORTANT

If the destination encoding is a character encoding scheme--such as ISO-2022-JP, which begins in ASCII and switches to other coded character sets through limited combinations of escape sequences--then you need to allocate enough space to accommodate escape sequences that signal switches. ISO-2022-JP requires 3 to 5 bytes for an escape sequence preceding the 1-byte or 2-byte character it introduces. If you allocate a buffer that is less than 5 bytes, the TECConvertText function could fail, depending on the text being converted.

To make sure that you receive all of the converted text, you should call the function TECFlushText when you are finished converting all the text in a particular text stream.