From ec778ef98b0b20e2bf4592b00d0a6ac39b69c511 Mon Sep 17 00:00:00 2001 From: Jay Berkenbilt Date: Tue, 8 Feb 2022 16:48:13 -0500 Subject: Add additional comments about new accessor methods --- include/qpdf/QPDFObjectHandle.hh | 26 +++++++++++++++++++------- manual/design.rst | 9 +++++++++ manual/release-notes.rst | 2 +- 3 files changed, 29 insertions(+), 8 deletions(-) diff --git a/include/qpdf/QPDFObjectHandle.hh b/include/qpdf/QPDFObjectHandle.hh index 359c9e19..e536c3cc 100644 --- a/include/qpdf/QPDFObjectHandle.hh +++ b/include/qpdf/QPDFObjectHandle.hh @@ -657,13 +657,25 @@ class QPDFObjectHandle // // In PDF files, objects have specific types, but there is nothing // that prevents PDF files from containing objects of types that - // aren't expected by the specification. Many of the accessors - // here expect objects of a particular type. Prior to qpdf 8, - // calling an accessor on a method of the wrong type, such as - // trying to get a dictionary key from an array, trying to get the - // string value of a number, etc., would throw an exception, but - // since qpdf 8, qpdf issues a warning and recovers using the - // following behavior: + // aren't expected by the specification. + // + // There are two flavors of accessor methods: + // + // * getSomethingValue() returns the value and issues a type + // warning if the type is incorrect. + // + // * getValueAsSomething() returns false if the value is the wrong + // type. Otherwise, it returns true and initializes a reference + // of the appropriate type. These methods never issue type + // warnings. + // + // The getSomethingValue() accessors and some of the other methods + // expect objects of a particular type. Prior to qpdf 8, calling + // an accessor on a method of the wrong type, such as trying to + // get a dictionary key from an array, trying to get the string + // value of a number, etc., would throw an exception, but since + // qpdf 8, qpdf issues a warning and recovers using the following + // behavior: // // * Requesting a value of the wrong type (int value from string, // array item from a scalar or dictionary, etc.) will return a diff --git a/manual/design.rst b/manual/design.rst index cbcded3e..0e50f858 100644 --- a/manual/design.rst +++ b/manual/design.rst @@ -746,6 +746,15 @@ and set return values in passed-in pointers, but this would complicate both the implementation and the use of the library for a case that is actually quite rare and largely avoidable. +*How can I avoid type warnings altogether?* For each +``getSomethingValue`` accessor that returns a value of the requested +type and issues a warning for objects of the wrong type, there is also +a ``getValueAsSomething`` method (since qpdf 10.6) that returns false +for objects of the wrong type and otherwise returns true and +initializes a reference. These methods never generate type warnings +and provide an alternative to explicitly checking the type of an +object before calling an accessor method. + .. _smart-pointers: Smart Pointers diff --git a/manual/release-notes.rst b/manual/release-notes.rst index b12e5e7f..a2d21ef8 100644 --- a/manual/release-notes.rst +++ b/manual/release-notes.rst @@ -99,7 +99,7 @@ For a detailed list of changes, please see the file - The newer accessor methods return a boolean indicating whether or not the object is of the expected type. If it is, a - reference of the correct type is returned. + reference to a variable of the correct type is initialized. In many cases, the new interfaces will enable more compact code and will also never generate type warnings. Thanks to M. Holger -- cgit v1.2.3-70-g09d2