[python] add encoding argument to Value.string

[Tom Tromey <tromey at redhat dot com>]

This adds an "encoding" argument to Value.string.
It also adds documentation for this method.

I was hoping to use this to write a pretty-printer for
basic_string<wchar_t>, but then I found out that Python 2.5 does not
have a UTF-32 or UCS-4 codec.  (I have read that 2.6 will, so this
will improve in the future.)

I'm not especially happy with the docs, feel free to improve them if
you like :-)

Tom

2008-11-21  Tom Tromey  <tromey@redhat.com>

	* python/python-value.c (value_object_methods) <string>: Accept
	varargs.
	(valpy_string): Accept optional encoding argument.

2008-11-21  Tom Tromey  <tromey@redhat.com>

	* gdb.texinfo (Values From Inferior): Document Value.string.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index fad65e2..18fe77f 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -18225,6 +18225,26 @@ The result @code{bar} will be a @code{gdb.Value} object holding the
 value pointed to by @code{foo}.
 @end defmethod
 
+@defmethod Value string @r{[}encoding@r{]}
+If this @code{gdb.Value} represents a string, then this method
+converts the contents to a Python string.  Otherwise, this method will
+throw an exception.
+
+Strings are recognized in a language-specific way; whether a given
+@code{gdb.Value} represents a string is determined by the current
+language.
+
+For C-like languages, a value is a string if it is a pointer to or an
+array of characters or ints.  The string is assumed to be terminated
+by a zero of the appropriate width.
+
+If the optional @var{encoding} argument is given, it must be a string
+naming the encoding of the string in the @code{gdb.Value}.  The Python
+codec machinery will be used to convert the string.  If @var{encoding}
+is not given, then the @code{target-charset} (@pxref{Character Sets})
+will be used.
+@end defmethod
+
 @defmethod Value type
 Return the type of this @code{gdb.Value}.  The result is a
 @code{gdb.Type} object.
diff --git a/gdb/python/python-value.c b/gdb/python/python-value.c
index 0712408..e8196ed 100644
--- a/gdb/python/python-value.c
+++ b/gdb/python/python-value.c
@@ -164,6 +164,13 @@ valpy_string (PyObject *self, PyObject *args)
   struct value *value = ((value_object *) self)->value;
   volatile struct gdb_exception except;
   PyObject *unicode;
+  const char *encoding = NULL;
+
+  if (!PyArg_ParseTuple (args, "|s", &encoding))
+    return NULL;
+
+  if (!encoding)
+    encoding = target_charset ();
 
   TRY_CATCH (except, RETURN_MASK_ALL)
     {
@@ -181,7 +188,7 @@ valpy_string (PyObject *self, PyObject *args)
       return NULL;
     }
 
-  unicode = target_string_to_unicode (buffer, length);
+  unicode = PyUnicode_Decode (buffer, length, encoding, NULL);
   xfree (buffer);
 
   return unicode;
@@ -905,7 +912,7 @@ static PyMethodDef value_object_methods[] = {
   { "cast", valpy_cast, METH_VARARGS, "Cast the value to the supplied type." },
   { "dereference", valpy_dereference, METH_NOARGS, "Dereferences the value." },
   { "type", valpy_type, METH_NOARGS, "Return type of the value." },
-  { "string", valpy_string, METH_NOARGS,
+  { "string", valpy_string, METH_VARARGS,
     "Return Unicode string representation of the value." },
   {NULL}  /* Sentinel */
 };