From a7d1f26ec3746758a6b5bfca1b3e514bc73ed0d1 Mon Sep 17 00:00:00 2001 From: Tom Tromey Date: Fri, 15 Nov 2024 08:02:25 -0700 Subject: [PATCH] Improvements to gdb.LazyString documentation I noticed the gdb.LazyString documentation did not mention how to create one. Then, while adding this, I found a couple other ways that this documentation could be clarified. Approved-By: Eli Zaretskii --- gdb/doc/python.texi | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi index fed9b5c1893..cc455483166 100644 --- a/gdb/doc/python.texi +++ b/gdb/doc/python.texi @@ -1279,9 +1279,10 @@ fetched and converted to the given length. @end defun @defun Value.lazy_string (@r{[}encoding @r{[}, length@r{]]}) -If this @code{gdb.Value} represents a string, then this method -converts the contents to a @code{gdb.LazyString} (@pxref{Lazy Strings -In Python}). Otherwise, this method will throw an exception. +This method attempts to convert this @code{gdb.Value} to a +@code{gdb.LazyString} (@pxref{Lazy Strings In Python}). Values of +array or pointer type can be converted; for other types, this method +will throw an exception. If the optional @var{encoding} argument is given, it must be a string naming the encoding of the @code{gdb.LazyString}. Some examples are: @@ -6971,11 +6972,13 @@ A @code{gdb.LazyString} is represented in @value{GDBN} as an that will be used to encode that region of memory, and a @code{length} to delimit the region of memory that represents the string. The difference between a @code{gdb.LazyString} and a string wrapped within -a @code{gdb.Value} is that a @code{gdb.LazyString} will be treated -differently by @value{GDBN} when printing. A @code{gdb.LazyString} is +a @code{gdb.Value} is that a @code{gdb.LazyString} will only be retrieved and encoded during printing, while a @code{gdb.Value} wrapping a string is immediately retrieved and encoded on creation. +A @code{gdb.LazyString} can be created using the +@code{gdb.Value.lazy_string} method (@pxref{Values From Inferior}). + A @code{gdb.LazyString} object has the following functions: @defun LazyString.value ()