'\"
'\" Copyright (c) 1998 Scriptics Corporation.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH encoding n "8.1" Tcl "Tcl Built-In Commands"
.so man.macros
.BS
.SH NAME
encoding \- Manipulate encodings
.SH SYNOPSIS
\fBencoding \fIoption\fR ?\fIarg arg ...\fR?
.BE
.SH INTRODUCTION
.PP
Strings in Tcl are logically a sequence of Unicode characters.
These strings are represented in memory as a sequence of bytes that
may be in one of several encodings: modified UTF\-8 (which uses 1 to 4
bytes per character), or a custom encoding start as 8 bit binary data.
.PP
Different operating system interfaces or applications may generate
strings in other encodings such as Shift\-JIS.  The \fBencoding\fR
command helps to bridge the gap between Unicode and these other
formats.
.SH DESCRIPTION
.PP
Performs one of several encoding related operations, depending on
\fIoption\fR.  The legal \fIoption\fRs are:
.TP
\fBencoding convertfrom\fR ?\fB-nocomplain\fR? ?\fB-failindex var\fR?
?\fIencoding\fR? \fIdata\fR
.
Convert \fIdata\fR to a Unicode string from the specified \fIencoding\fR.  The
characters in \fIdata\fR are 8 bit binary data.  The resulting
sequence of bytes is a string created by applying the given \fIencoding\fR
to the data. If \fIencoding\fR is not specified, the current
system encoding is used.
.
The call fails on convertion errors, like an incomplete utf-8 sequence.
The option \fB-failindex\fR is followed by a variable name. The variable
is set to \fI-1\fR if no conversion error occured. It is set to the
first error location in \fIdata\fR in case of a conversion error. All data
until this error location is transformed and retured. This option may not
be used together with \fB-nocomplain\fR.
.
The call does not fail on conversion errors, if the option
\fB-nocomplain\fR is given. In this case, any error locations are replaced
by \fB?\fR. Incomplete sequences are written verbatim to the output string.
The purpose of this switch is to gain compatibility to prior versions of TCL.
It is not recommended for any other usage.
.TP
\fBencoding convertto\fR ?\fB-nocomplain\fR? ?\fB-failindex var\fR?
?\fIencoding\fR? \fIstring\fR
.
Convert \fIstring\fR from Unicode to the specified \fIencoding\fR.
The result is a sequence of bytes that represents the converted
string.  Each byte is stored in the lower 8-bits of a Unicode
character (indeed, the resulting string is a binary string as far as
Tcl is concerned, at least initially).  If \fIencoding\fR is not
specified, the current system encoding is used.
.
The call fails on convertion errors, like a Unicode character not representable
in the given \fIencoding\fR.
.
The option \fB-failindex\fR is followed by a variable name. The variable
is set to \fI-1\fR if no conversion error occured. It is set to the
first error location in \fIdata\fR in case of a conversion error. All data
until this error location is transformed and retured. This option may not
be used together with \fB-nocomplain\fR.
.
The call does not fail on conversion errors, if the option
\fB-nocomplain\fR is given. In this case, any error locations are replaced
by \fB?\fR. Incomplete sequences are written verbatim to the output string.
The purpose of this switch is to gain compatibility to prior versions of TCL.
It is not recommended for any other usage.
.TP
\fBencoding dirs\fR ?\fIdirectoryList\fR?
.
Tcl can load encoding data files from the file system that describe
additional encodings for it to work with. This command sets the search
path for \fB*.enc\fR encoding data files to the list of directories
\fIdirectoryList\fR. If \fIdirectoryList\fR is omitted then the
command returns the current list of directories that make up the
search path. It is an error for \fIdirectoryList\fR to not be a valid
list. If, when a search for an encoding data file is happening, an
element in \fIdirectoryList\fR does not refer to a readable,
searchable directory, that element is ignored.
.TP
\fBencoding names\fR
.
Returns a list containing the names of all of the encodings that are
currently available.
The encodings
.QW utf-8
and
.QW iso8859-1
are guaranteed to be present in the list.
.TP
\fBencoding system\fR ?\fIencoding\fR?
.
Set the system encoding to \fIencoding\fR. If \fIencoding\fR is
omitted then the command returns the current system encoding.  The
system encoding is used whenever Tcl passes strings to system calls.
.SH EXAMPLE
.PP
The following example converts a byte sequence in Japanese euc-jp encoding to a TCL string:
.PP
.CS
set s [\fBencoding convertfrom\fR euc-jp "\exA4\exCF"]
.CE
.PP
The result is the unicode codepoint:
.QW "\eu306F" ,
which is the Hiragana letter HA.
.PP
The following example detects the error location in an incomplete UTF-8 sequence:
.PP
.CS
% set s [\fBencoding convertfrom\fR -failindex i utf-8 "A\exC3"]
A
% set i
1
.CE
.PP
The following example detects the error location while transforming to ISO8859-1
(ISO-Latin 1):
.PP
.CS
% set s [\fBencoding convertto\fR -failindex i utf-8 "A\eu0141"]
A
% set i
1
.CE
.PP
.SH "SEE ALSO"
Tcl_GetEncoding(3)
.SH KEYWORDS
encoding, unicode
.\" Local Variables:
.\" mode: nroff
.\" End: