diff options
Diffstat (limited to 'include')
-rw-r--r-- | include/qpdf/JSON.hh | 35 | ||||
-rw-r--r-- | include/qpdf/QPDFObjectHandle.hh | 32 |
2 files changed, 41 insertions, 26 deletions
diff --git a/include/qpdf/JSON.hh b/include/qpdf/JSON.hh index ef1632c2..63c858b1 100644 --- a/include/qpdf/JSON.hh +++ b/include/qpdf/JSON.hh @@ -183,17 +183,30 @@ class JSON // // * The schema is a nested structure containing dictionaries, // single-element arrays, and strings only. - // * Recursively walk the schema. - // * If the current value is a dictionary, this object must have - // a dictionary in the same place with the same keys. If flags - // contains f_optional, a key in the schema does not have to - // be present in the object. Otherwise, all keys have to be - // present. Any key in the object must be present in the - // schema. - // * If the current value is an array, this object must have an - // array in the same place. The schema's array must contain a - // single element, which is used as a schema to validate each - // element of this object's corresponding array. + // * Recursively walk the schema. In the items below, "schema + // object" refers to an object in the schema, and "checked + // object" refers to the correspondingi part of the object + // being checked. + // * If the schema object is a dictionary, the checked object + // must have a dictionary in the same place with the same + // keys. If flags contains f_optional, a key in the schema + // does not have to be present in the object. Otherwise, all + // keys have to be present. Any key in the object must be + // present in the schema. + // * If the schema object is an array of length 1, the checked + // object may either be a single item or an array of items. + // The single item or each element of the checked object's + // array is validated against the single element of the + // schema's array. The rationale behind this logic is that a + // single element may appear wherever the schema allows a + // variable-length array. This makes it possible to start + // allowing an array in the future where a single element was + // previously required without breaking backward + // compatibility. + // * If the schema object is an array of length > 1, the checked + // object must be an array of the same length. In this case, + // each element of the checked object array is validated + // against the corresponding element of the schema array. // * Otherwise, the value must be a string whose value is a // description of the object's corresponding value, which may // have any type. diff --git a/include/qpdf/QPDFObjectHandle.hh b/include/qpdf/QPDFObjectHandle.hh index 790acccd..7ea6b062 100644 --- a/include/qpdf/QPDFObjectHandle.hh +++ b/include/qpdf/QPDFObjectHandle.hh @@ -999,18 +999,15 @@ class QPDFObjectHandle // Mutator methods. - // Since qpdf 11: when a mutator object returns QPDFObjectHandle&, - // it is a reference to the object itself. This makes it possible - // to use a fluent style. For example: + // Since qpdf 11: for mutators that may add or remove an item, + // there are additional versions whose names contain "AndGet" that + // return the added or removed item. For example: // - // array.appendItem(i1).appendItem(i2); - // - // would append i1 and then i2 to the array. There are also items - // that end with AndGet and return a QPDFObjectHandle. These - // return the newly added object. For example: - // - // auto new_dict = dict.replaceKeyAndGet( + // auto new_dict = dict.replaceKeyAndGetNew( // "/New", QPDFObjectHandle::newDictionary()); + // + // auto old_value = dict.replaceKeyAndGetOld( + // "/New", "(something)"_qpdf); // Recursively copy this object, making it direct. An exception is // thrown if a loop is detected. With allow_streams true, keep @@ -1036,20 +1033,20 @@ class QPDFObjectHandle void insertItem(int at, QPDFObjectHandle const& item); // Like insertItem but return the item that was inserted. QPDF_DLL - QPDFObjectHandle insertItemAndGet(int at, QPDFObjectHandle const& item); + QPDFObjectHandle insertItemAndGetNew(int at, QPDFObjectHandle const& item); // Append an item to an array. QPDF_DLL void appendItem(QPDFObjectHandle const& item); // Append an item, and return the newly added item. QPDF_DLL - QPDFObjectHandle appendItemAndGet(QPDFObjectHandle const& item); + QPDFObjectHandle appendItemAndGetNew(QPDFObjectHandle const& item); // Remove the item at that position, reducing the size of the // array by one. QPDF_DLL void eraseItem(int at); // Erase and item and return the item that was removed. QPDF_DLL - QPDFObjectHandle eraseItemAndGet(int at); + QPDFObjectHandle eraseItemAndGetOld(int at); // Mutator methods for dictionary objects @@ -1060,14 +1057,19 @@ class QPDFObjectHandle // Replace value of key and return the value. QPDF_DLL QPDFObjectHandle - replaceKeyAndGet(std::string const& key, QPDFObjectHandle const& value); + replaceKeyAndGetNew(std::string const& key, QPDFObjectHandle const& value); + // Replace value of key and return the old value, or null if the + // key was previously not present. + QPDF_DLL + QPDFObjectHandle + replaceKeyAndGetOld(std::string const& key, QPDFObjectHandle const& value); // Remove key, doing nothing if key does not exist. QPDF_DLL void removeKey(std::string const& key); // Remove key and return the old value. If the old value didn't // exist, return a null object. QPDF_DLL - QPDFObjectHandle removeKeyAndGet(std::string const& key); + QPDFObjectHandle removeKeyAndGetOld(std::string const& key); // ABI: Remove in qpdf 12 [[deprecated("use replaceKey -- it does the same thing")]] QPDF_DLL void |