summaryrefslogtreecommitdiff
path: root/doc/ref/api-io.texi
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2010-01-07 11:00:37 +0100
committerLudovic Courtès <ludo@gnu.org>2010-01-07 11:10:35 +0100
commit7b0419128bce68f48a158292430ed4a7202aa1b1 (patch)
treeda697b566d45d144d2c23310ac34de7c29e60666 /doc/ref/api-io.texi
parent29bcdbb05948a5f12d2d8cb36a0c3c582e738be3 (diff)
downloadguile-7b0419128bce68f48a158292430ed4a7202aa1b1.tar.gz
Have string ports honor `%default-port-encoding'.
* libguile/strports.c (scm_i_mkstrport): Remove. (scm_mkstrport): Don't change the port's encoding to UTF-8; convert STR to the default port encoding. (scm_strport_to_string): Fix documentation & indentation. * libguile/strports.h (scm_i_mkstrport): Remove. * test-suite/lib.scm (exception:encoding-error): New variable. (format-test-name): Set `%default-port-encoding' to "UTF-8". * test-suite/tests/ports.test ("string ports")["%default-port-encoding is honored", "suitable encoding [latin-1]", "suitable encoding [latin-3]", "wrong encoding"]: New tests. * test-suite/tests/r6rs-ports.test ("7.2.11 Binary Output")["put-bytevector with UTF-16 string port", "put-bytevector with wrong-encoding string port"]: New tests. * test-suite/tests/reader.test (read-string): Set `%default-port-encoding' to `#f'. ("reading")["unprintable symbol"]: Use a string that doesn't contain zeros. * doc/ref/api-io.texi (String Ports): Document encoding issues with `call-with-output-string' and `with-output-to-string'.
Diffstat (limited to 'doc/ref/api-io.texi')
-rw-r--r--doc/ref/api-io.texi26
1 files changed, 25 insertions, 1 deletions
diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index eb5338c0d..a1f4221e2 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2009
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2009, 2010
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@@ -972,6 +972,28 @@ away from its default.
Calls the one-argument procedure @var{proc} with a newly created output
port. When the function returns, the string composed of the characters
written into the port is returned. @var{proc} should not close the port.
+
+Note that which characters can be written to a string port depend on the port's
+encoding. The default encoding of string ports is specified by the
+@code{%default-port-encoding} fluid (@pxref{Ports,
+@code{%default-port-encoding}}). For instance, it is an error to write Greek
+letter alpha to an ISO-8859-1-encoded string port since this character cannot be
+represented with ISO-8859-1:
+
+@example
+(define alpha (integer->char #x03b1)) ; GREEK SMALL LETTER ALPHA
+
+(with-fluids ((%default-port-encoding "ISO-8859-1"))
+ (call-with-output-string
+ (lambda (p)
+ (display alpha p))))
+
+@result{}
+Throw to key `encoding-error'
+@end example
+
+Changing the string port's encoding to a Unicode-capable encoding such as UTF-8
+solves the problem.
@end deffn
@deffn {Scheme Procedure} call-with-input-string string proc
@@ -985,6 +1007,8 @@ read. The value yielded by the @var{proc} is returned.
Calls the zero-argument procedure @var{thunk} with the current output
port set temporarily to a new string port. It returns a string
composed of the characters written to the current output.
+
+See @code{call-with-output-string} above for character encoding considerations.
@end deffn
@deffn {Scheme Procedure} with-input-from-string string thunk