From c08e96ef0dd8f048699b1ba00e2ce7fee12edaa8 Mon Sep 17 00:00:00 2001 From: kobewi Date: Sat, 29 Apr 2023 00:05:16 +0200 Subject: [PATCH] Improve and document PackedDataContainer --- core/io/packed_data_container.cpp | 11 +++++----- core/io/packed_data_container.h | 1 - doc/classes/PackedDataContainer.xml | 29 ++++++++++++++++++++++---- doc/classes/PackedDataContainerRef.xml | 25 +++++++++++++++++++++- 4 files changed, 54 insertions(+), 12 deletions(-) diff --git a/core/io/packed_data_container.cpp b/core/io/packed_data_container.cpp index 6c16401f179..ce4edb18fe1 100644 --- a/core/io/packed_data_container.cpp +++ b/core/io/packed_data_container.cpp @@ -320,6 +320,8 @@ uint32_t PackedDataContainer::_pack(const Variant &p_data, Vector &tmpd } Error PackedDataContainer::pack(const Variant &p_data) { + ERR_FAIL_COND_V_MSG(p_data.get_type() != Variant::ARRAY && p_data.get_type() != Variant::DICTIONARY, ERR_INVALID_DATA, "PackedDataContainer can pack only Array and Dictionary type."); + Vector tmpdata; HashMap string_cache; _pack(p_data, tmpdata, string_cache); @@ -361,7 +363,9 @@ void PackedDataContainer::_bind_methods() { ClassDB::bind_method(D_METHOD("pack", "value"), &PackedDataContainer::pack); ClassDB::bind_method(D_METHOD("size"), &PackedDataContainer::size); - ADD_PROPERTY(PropertyInfo(Variant::PACKED_BYTE_ARRAY, "__data__"), "_set_data", "_get_data"); + BIND_METHOD_ERR_RETURN_DOC("pack", ERR_INVALID_DATA); + + ADD_PROPERTY(PropertyInfo(Variant::PACKED_BYTE_ARRAY, "__data__", PROPERTY_HINT_NONE, "", PROPERTY_USAGE_STORAGE | PROPERTY_USAGE_INTERNAL), "_set_data", "_get_data"); } ////////////////// @@ -378,16 +382,11 @@ Variant PackedDataContainerRef::_iter_get(const Variant &p_iter) { return from->_iter_get_ofs(p_iter, offset); } -bool PackedDataContainerRef::_is_dictionary() const { - return from->_type_at_ofs(offset) == PackedDataContainer::TYPE_DICT; -} - void PackedDataContainerRef::_bind_methods() { ClassDB::bind_method(D_METHOD("size"), &PackedDataContainerRef::size); ClassDB::bind_method(D_METHOD("_iter_init"), &PackedDataContainerRef::_iter_init); ClassDB::bind_method(D_METHOD("_iter_get"), &PackedDataContainerRef::_iter_get); ClassDB::bind_method(D_METHOD("_iter_next"), &PackedDataContainerRef::_iter_next); - ClassDB::bind_method(D_METHOD("_is_dictionary"), &PackedDataContainerRef::_is_dictionary); } Variant PackedDataContainerRef::getvar(const Variant &p_key, bool *r_valid) const { diff --git a/core/io/packed_data_container.h b/core/io/packed_data_container.h index a77970a0bd1..cc9996101e2 100644 --- a/core/io/packed_data_container.h +++ b/core/io/packed_data_container.h @@ -94,7 +94,6 @@ public: Variant _iter_init(const Array &p_iter); Variant _iter_next(const Array &p_iter); Variant _iter_get(const Variant &p_iter); - bool _is_dictionary() const; int size() const; virtual Variant getvar(const Variant &p_key, bool *r_valid = nullptr) const override; diff --git a/doc/classes/PackedDataContainer.xml b/doc/classes/PackedDataContainer.xml index addfdbed6b5..8b500b41bd8 100644 --- a/doc/classes/PackedDataContainer.xml +++ b/doc/classes/PackedDataContainer.xml @@ -1,26 +1,47 @@ + Efficiently packs and serializes [Array] or [Dictionary]. + [PackedDataContainer] can be used to efficiently store data from untyped containers. The data is packed into raw bytes and can be saved to file. Only [Array] and [Dictionary] can be stored this way. + You can retrieve the data by iterating on the container, which will work as if iterating on the packed data itself. If the packed container is a [Dictionary], the data can be retrieved by key names ([String]/[StringName] only). + [codeblock] + var data = { "key": "value", "another_key": 123, "lock": Vector2() } + var packed = PackedDataContainer.new() + packed.pack(data) + ResourceSaver.save(packed, "packed_data.res") + [/codeblock] + [codeblock] + var container = load("packed_data.res") + for key in container: + prints(key, container[key]) + + # Prints: + # key value + # lock (0, 0) + # another_key 123 + [/codeblock] + Nested containers will be packed recursively. While iterating, they will be returned as [PackedDataContainerRef]. + + + Packs the given container into a binary representation. The [param value] must be either [Array] or [Dictionary], any other type will result in invalid data error. + [b]Note:[/b] Subsequent calls to this method will overwrite the existing data. + Returns the size of the packed container (see [method Array.size] and [method Dictionary.size]). - - - - diff --git a/doc/classes/PackedDataContainerRef.xml b/doc/classes/PackedDataContainerRef.xml index 47285fa8d60..440673d9b09 100644 --- a/doc/classes/PackedDataContainerRef.xml +++ b/doc/classes/PackedDataContainerRef.xml @@ -1,9 +1,31 @@ - Reference-counted version of [PackedDataContainer]. + Internal class used by [PackedDataContainer]. + When packing nested containers using [PackedDataContainer], they are recursively packed into [PackedDataContainerRef] (only applies to [Array] and [Dictionary]). Their data can be retrieved the same way as from [PackedDataContainer]. + [codeblock] + var packed = PackedDataContainer.new() + packed.pack([1, 2, 3, ["abc", "def"], 4, 5, 6]) + + for element in packed: + if element is PackedDataContainerRef: + for subelement in element: + print("::", subelement) + else: + print(element) + + # Prints: + # 1 + # 2 + # 3 + # ::abc + # ::def + # 4 + # 5 + # 6 + [/codeblock] @@ -11,6 +33,7 @@ + Returns the size of the packed container (see [method Array.size] and [method Dictionary.size]).