<commit_before>namespace collections {

    const char *kCommentObject = "creates new container object. returns container identifier (integer number).\n"
        "identifier is the thing you will have to pass to the most of container's functions as a first argument";

#define ARGS(...)   #__VA_ARGS__

    class tes_object : public reflection::class_meta_mixin_t< tes_object > {
    public:

        typedef object_stack_ref& ref;

        REGISTER_TES_NAME("JValue");

        void additionalSetup() {
            metaInfo.comment = "Each container (JArray, JMap & JFormMap) inherits JValue functionality";
        }

        static object_base* retain(ref obj, const char* tag = nullptr) {
            if (obj) {
                obj->tes_retain();

                if (tag) {
                    obj->set_tag(tag);
                }

                return obj.get();
            }

            return nullptr;
        }
        REGISTERF2(retain, "*",
"Retains and returns the object.\n\
All containers that were created with object* or objectWith* methods are automatically destroyed after some amount of time (~10 seconds)\n\
To keep object alive you must retain it once and you have to __release__ it when you do not need it anymore (also to not pollute save file).\n\
An alternative to retain-release is store object in JDB container"
            );

        template<class T>
        static T* object() {
            return T::object(tes_context::instance());
        }

        static object_base* release(ref obj) {
            if (obj) {
                obj->tes_release();
            }

            return nullptr;
        }
        REGISTERF2(release, "*", "releases the object and returns zero, so you can release and nullify with one line of code: object = JVlaue.release(object)");

        static object_base* releaseAndRetain(ref previousObject, ref newObject, const char* tag = nullptr) {
            if (previousObject != newObject) {
                if (previousObject) {
                    previousObject->tes_release();
                }

                retain(newObject, tag);
            }

            return newObject.get();
        }
        REGISTERF2(releaseAndRetain, "previousObject newObject tag=None",
"just a union of retain-release calls. releases previousObject, retains and returns newObject.\n\
useful for those who use Papyrus properties instead of manual (and more error-prone) release-retain object lifetime management");

        static void releaseObjectsWithTag(const char *tag) {
            if (!tag) {
                return;
            }

            auto objects = tes_context::instance().filter_objects([tag](const object_base& obj) {
                return obj.has_equal_tag(tag);
            });

            for (auto& ref : objects) {
                while (ref->_tes_refCount != 0) {
                    ref->tes_release();
                }
            }
        }

        static bool isArray(ref obj) {
            return obj->as<array>() != nullptr;
        }
        REGISTERF2(isArray, "*", "returns true if object is map, array or formmap container");

        static bool isMap(ref obj) {
            return obj->as<map>() != nullptr;
        }
        REGISTERF2(isMap, "*", nullptr);

        static bool isFormMap(ref obj) {
            return obj->as<form_map>() != nullptr;
        }
        REGISTERF2(isFormMap, "*", nullptr);

        static bool empty(ref obj) {
            return count(obj) == 0;
        }
        REGISTERF2(empty, "*", "returns true, if container is empty");

        static SInt32 count(ref obj) {
            return obj ? obj->s_count() : 0;<commit_msg>improve ‘retain-release’ comments. hope they are more informative now<commit_after>namespace collections {

    const char *kCommentObject = "creates new container object. returns container identifier (integer number).\n"
        "identifier is the thing you will have to pass to the most of container's functions as a first argument";

#define ARGS(...)   #__VA_ARGS__

    class tes_object : public reflection::class_meta_mixin_t< tes_object > {
    public:

        typedef object_stack_ref& ref;

        REGISTER_TES_NAME("JValue");

        void additionalSetup() {
            metaInfo.comment = "Each container (JArray, JMap & JFormMap) inherits JValue functionality";
        }

        static object_base* retain(ref obj, const char* tag = nullptr) {
            if (obj) {
                obj->tes_retain();

                if (tag) {
                    obj->set_tag(tag);
                }

                return obj.get();
            }

            return nullptr;
        }
        REGISTERF2(retain, "* tag=None",
"Retains and returns the object. Purpose - extend object lifetime.\n\
Newly created object if not retained or not referenced/contained by another container directly or indirectly gets destoyed after ~10 seconds due to absence of owners.\n\
Retain increases amount of owners object have by 1. The retainer is responsible for releasing object later.\n\
Object have extended lifetime if JDB or JFormDB or any other container references/owns/contains object directly or indirectly.\n\
It's recommended to set a tag (any unique string will fit - mod name for ex.) - later you'll be able to release all objects with selected tag even if identifier has been lost")
            );

        template<class T>
        static T* object() {
            return T::object(tes_context::instance());
        }

        static object_base* release(ref obj) {
            if (obj) {
                obj->tes_release();
            }

            return nullptr;
        }
        REGISTERF2(release, "*", "releases the object and returns zero, so you can release and nullify with one line of code: object = JValue.release(object)");

        static object_base* releaseAndRetain(ref previousObject, ref newObject, const char* tag = nullptr) {
            if (previousObject != newObject) {
                if (previousObject) {
                    previousObject->tes_release();
                }

                retain(newObject, tag);
            }

            return newObject.get();
        }
        REGISTERF2(releaseAndRetain, "previousObject newObject tag=None",
"Just a union of retain-release calls. Releases previousObject, retains and returns newObject.\n\
It's recommended to set tag (any unique string will fit - mod name for ex.) - later you'll be able to release all objects with selected tag even if identifier was lost.");

        static void releaseObjectsWithTag(const char *tag) {
            if (!tag) {
                return;
            }

            auto objects = tes_context::instance().filter_objects([tag](const object_base& obj) {
                return obj.has_equal_tag(tag);
            });

            for (auto& ref : objects) {
                while (ref->_tes_refCount != 0) {
                    ref->tes_release();
                }
            }
        }
        REGISTERF2(releaseObjectsWithTag, "tag",
"For maintanance - releases lost (and not lost) objects with given tag.\n"
"Complements all retain calls objects with given tag received with release calls.\n"
"See 'object lifetime management' section for more information");

        static bool isArray(ref obj) {
            return obj->as<array>() != nullptr;
        }
        REGISTERF2(isArray, "*", "returns true if object is map, array or formmap container");

        static bool isMap(ref obj) {
            return obj->as<map>() != nullptr;
        }
        REGISTERF2(isMap, "*", nullptr);

        static bool isFormMap(ref obj) {
            return obj->as<form_map>() != nullptr;
        }
        REGISTERF2(isFormMap, "*", nullptr);

        static bool empty(ref obj) {
            return count(obj) == 0;
        }
        REGISTERF2(empty, "*", "returns true, if container is empty");

        static SInt32 count(ref obj) {
            return obj ? obj->s_count() : 0;
{'fraction_non_alphanumeric': 0.09395804547167441, 'fraction_numerical': 0.0037683708076874764, 'mean_word_length': 2.0670261941448382, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 33, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3280888', 'n_tokens_mistral': 2119, 'n_tokens_neox': 2011, 'n_words': 709}