From patchwork Sat Sep 24 14:36:59 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Marvin Scholz X-Patchwork-Id: 38214 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a20:3b1c:b0:96:9ee8:5cfd with SMTP id c28csp1156822pzh; Sat, 24 Sep 2022 07:37:58 -0700 (PDT) X-Google-Smtp-Source: AMsMyM4CBH+/SCwfvPHaY57eM7jloqXjUqvDYWfZUN1qTjljB7JvsNoKP1U29+zuq7WEohqkdQkF X-Received: by 2002:a17:907:3e90:b0:781:cfa5:18a with SMTP id hs16-20020a1709073e9000b00781cfa5018amr11086070ejc.511.1664030278708; Sat, 24 Sep 2022 07:37:58 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1664030278; cv=none; d=google.com; s=arc-20160816; b=i7X7DjHk0L1rvSkmIAPDFF6mv7G2kd2/9RY0qzKt9ADflxDtINGoPfhCNeBvuNFq+i H1uYtkj4azOV0YScFVN/GEixLtwhT/7UuTkcQIqv0kJOZLBFbkVyYprG69Mj9eFHyp5w ZbHc+/wpQp/yXzPdvupLoe7UrKY88hrsPOnWVlYjXMVfHTDypcjrT4hfgG17SLWoEqG2 ShcAJrSRbpFPMJIEVhehXQH5A+P+Hcl8I9fktRFeP+zZhnr4BWobov3Tt6qCevhDO8aN JSandjGKiXh0R/6YsPdpMf7cwSZe5uKIm+Bbzeq9mBSsao6X0cGdgiB0pdyiEPjt0tc1 A6MA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:cc:reply-to :list-subscribe:list-help:list-post:list-archive:list-unsubscribe :list-id:precedence:subject:mime-version:references:in-reply-to :message-id:date:to:from:dkim-signature:delivered-to; bh=QnFS/w/25YMjkMYt1DYXhUI1+/pFLyHl313hQ0CqLRc=; b=NtYU/U38K035PxTBdc/YDfaP8MfPT0byCLp1qVf8wVXl8MWDysVaq27Xb4xja7iaWk NOjnyozZMDhDhiWcGZWWTK1KuI3i6LQazLt1laFAdBNW8iEpp4ShorT0ZnJW1cHzpS37 W74qd3ojsiaxoGrYEFyTztORakCfFrUjjWXs46gOgEOZXi1hxO2i12+f3qtpsaq0h4kE mF2rWiqv38+e220WzmRjV8uBLOOvPpWYSqUUxwo90VTxC/o3AkSq0KL0JLemVxGvtnVD bVPLnozZGfjQ+Bsz/qdQnX8PfGn8HSz6WnLw0vdbqLW2g4eA0VC+j9fWpgHPHd3N5uIU Mikg== ARC-Authentication-Results: i=1; mx.google.com; dkim=neutral (body hash did not verify) header.i=@gmail.com header.s=20210112 header.b=hqf6zgNA; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org; dmarc=fail (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id b14-20020a17090630ce00b00718d0604af4si9488459ejb.604.2022.09.24.07.37.58; Sat, 24 Sep 2022 07:37:58 -0700 (PDT) Received-SPF: pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) client-ip=79.124.17.100; Authentication-Results: mx.google.com; dkim=neutral (body hash did not verify) header.i=@gmail.com header.s=20210112 header.b=hqf6zgNA; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org; dmarc=fail (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id A04B768B9FE; Sat, 24 Sep 2022 17:37:27 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from mail-ed1-f42.google.com (mail-ed1-f42.google.com [209.85.208.42]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id E677368B96D for ; Sat, 24 Sep 2022 17:37:20 +0300 (EEST) Received: by mail-ed1-f42.google.com with SMTP id y8so3630022edc.10 for ; Sat, 24 Sep 2022 07:37:20 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date; bh=k+aR8Lst5xdPqM35x57gy/aqrAXMy2jfOLk45Urjge4=; b=hqf6zgNAnnH1DIL/t30YQ64Hs02dbe/YDzOqLJQiBPmYG9dVizN/bNd8KBaSZTGN6s wvoeMGC3SaGcjOpijy2c5dF5TZz9by7YcWRSrnv0hDnrGmAtaxl38p5QVBKDpPozsQmk SmEFYsYgcliWhfu/M7mnKJ3Cu6/hXlODq00pMBgv091mH94EWWQmK82cFoIorSRSSddg IlG5ZRwP/p1cNCrznPFNlyzW8a4hD5fdbYogbXy3aq5Nvyy3U5sGG6EtGqeuFrS5kzuw 0WvwVKq2s8zy8lvTm8n+uEqd7XrHb9RhLMxfNzYJYQcPkLwyCQvJIN7h4jec7HNqHmd6 HOxw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date; bh=k+aR8Lst5xdPqM35x57gy/aqrAXMy2jfOLk45Urjge4=; b=LtdBYl30pQC1n1KEDJP6flJquxxAg0rJtncfyd2LLMVNubt47v8MF7KKbTID+C/oEg P30x3+/NbR0tOI023HRwxAK44aUwVA2iZa/pKVRyGo0XaSeu7HyPLJI9LIbDs6gDQF7s Uilm+7lAAMGc1qJ/HHQhI/obBEeJX3/ynBo0FNDzyJo1DjQ72oDGcLpDyEyMp7bWoGr9 EWPHxkjaW+t7DES9GRoUc8droverMuGwoIFY2CAWYz7IEQum5hQyV5Y4YlXv+uqnqW/4 r5TRqAoF7M3hnvRloXs/FIf0pQArEWamxtN5Rqd8nk5dpYFESvwRHyC+LISLbAZsDieC tWqQ== X-Gm-Message-State: ACrzQf2A3saZiNabdWlRbeTDa2Go/oaetMPnCoz6CyjGUVzRX3QQVLah iWHhSiV/rSq75uVxQpXTx1EKVPywOdalGg== X-Received: by 2002:a05:6402:50ca:b0:451:a711:1389 with SMTP id h10-20020a05640250ca00b00451a7111389mr13319652edb.239.1664030240175; Sat, 24 Sep 2022 07:37:20 -0700 (PDT) Received: from MBP-von-Marvin.citadel.scalie.me (84-112-104-25.cable.dynamic.surfer.at. [84.112.104.25]) by smtp.gmail.com with ESMTPSA id u17-20020a50c2d1000000b0044e8d0682b2sm7970504edf.71.2022.09.24.07.37.19 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 24 Sep 2022 07:37:19 -0700 (PDT) From: Marvin Scholz To: ffmpeg-devel@ffmpeg.org Date: Sat, 24 Sep 2022 16:36:59 +0200 Message-Id: <20220924143659.74756-5-epirat07@gmail.com> X-Mailer: git-send-email 2.37.0 (Apple Git-136) In-Reply-To: <20220924143659.74756-1-epirat07@gmail.com> References: <20220922020216.46589-1-epirat07@gmail.com> <20220924143659.74756-1-epirat07@gmail.com> MIME-Version: 1.0 Subject: [FFmpeg-devel] [PATCH v2 5/5] avutil/dict: Improve documentation X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: FFmpeg development discussions and patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: FFmpeg development discussions and patches Cc: Marvin Scholz Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: VVcwRludzMVf Mostly consistent formatting and consistently ordering of warnings/notes to be next to the description. Additionally group the AV_DICT_* macros. --- libavutil/dict.h | 91 +++++++++++++++++++++++++++++------------------- 1 file changed, 55 insertions(+), 36 deletions(-) diff --git a/libavutil/dict.h b/libavutil/dict.h index 344afb452b..e4bc330a44 100644 --- a/libavutil/dict.h +++ b/libavutil/dict.h @@ -41,13 +41,15 @@ * @brief Simple key:value store * * @{ - * Dictionaries are used for storing key:value pairs. To create - * an AVDictionary, simply pass an address of a NULL pointer to - * av_dict_set(). NULL can be used as an empty dictionary wherever - * a pointer to an AVDictionary is required. - * Use av_dict_get() to retrieve an entry and av_dict_iterate() to - * iterate over all entries and finally av_dict_free() to free the - * dictionary and all its contents. + * Dictionaries are used for storing key-value pairs. + * + * - To **create an AVDictionary**, simply pass an address of a NULL + * pointer to av_dict_set(). NULL can be used as an empty dictionary + * wherever a pointer to an AVDictionary is required. + * - To **insert an entry**, use av_dict_set(). + * - Use av_dict_get() to **retrieve an entry**. + * - To **iterate over all entries**, use av_dict_iterate(). + * - In order to **free the dictionary and all its contents**, use av_dict_free(). * @code AVDictionary *d = NULL; // "create" an empty dictionary @@ -59,13 +61,18 @@ char *v = av_strdup("value"); // you can avoid copying them like this av_dict_set(&d, k, v, AV_DICT_DONT_STRDUP_KEY | AV_DICT_DONT_STRDUP_VAL); - while (t = av_dict_iterate(d, t)) { + while ((t = av_dict_iterate(d, t))) { <....> // iterate over all entries in d } av_dict_free(&d); @endcode */ +/** + * @name AVDictionary Flags + * Flags that influence behavior of the matching of keys or insertion to the dictionary. + * @{ + */ #define AV_DICT_MATCH_CASE 1 /**< Only get an entry with exact-case key match. Only relevant in av_dict_get(). */ #define AV_DICT_IGNORE_SUFFIX 2 /**< Return first entry in a dictionary whose first part corresponds to the search key, ignoring the suffix of the found key string. Only relevant in av_dict_get(). */ @@ -73,10 +80,13 @@ allocated with av_malloc() or another memory allocation function. */ #define AV_DICT_DONT_STRDUP_VAL 8 /**< Take ownership of a value that's been allocated with av_malloc() or another memory allocation function. */ -#define AV_DICT_DONT_OVERWRITE 16 ///< Don't overwrite existing entries. +#define AV_DICT_DONT_OVERWRITE 16 /**< Don't overwrite existing entries. */ #define AV_DICT_APPEND 32 /**< If the entry already exists, append to it. Note that no - delimiter is added, the strings are simply concatenated. */ + delimiter is added, the strings are simply concatenated. */ #define AV_DICT_MULTIKEY 64 /**< Allow to store several equal keys in the dictionary */ +/** + * @} + */ typedef struct AVDictionaryEntry { char *key; @@ -91,11 +101,13 @@ typedef struct AVDictionary AVDictionary; * The returned entry key or value must not be changed, or it will * cause undefined behavior. * - * @param prev Set to the previous matching element to find the next. - * If set to NULL the first matching element is returned. - * @param key matching key - * @param flags a collection of AV_DICT_* flags controlling how the entry is retrieved - * @return found entry or NULL in case no matching entry was found in the dictionary + * @param prev Set to the previous matching element to find the next. + * If set to NULL the first matching element is returned. + * @param key Matching key + * @param flags A collection of AV_DICT_* flags controlling how the + * entry is retrieved + * + * @return Found entry or NULL in case no matching entry was found in the dictionary */ AVDictionaryEntry *av_dict_get(const AVDictionary *m, const char *key, const AVDictionaryEntry *prev, int flags); @@ -144,20 +156,21 @@ int av_dict_count(const AVDictionary *m); * @warning Adding a new entry to a dictionary invalidates all existing entries * previously returned with av_dict_get() or av_dict_iterate(). * - * @param pm pointer to a pointer to a dictionary struct. If *pm is NULL - * a dictionary struct is allocated and put in *pm. - * @param key entry key to add to *pm (will either be av_strduped or added as a new key depending on flags) - * @param value entry value to add to *pm (will be av_strduped or added as a new key depending on flags). - * Passing a NULL value will cause an existing entry to be deleted. - * @return >= 0 on success otherwise an error code <0 + * @param pm Pointer to a pointer to a dictionary struct. If *pm is NULL + * a dictionary struct is allocated and put in *pm. + * @param key Entry key to add to *pm (will either be av_strduped or added as a new key depending on flags) + * @param value Entry value to add to *pm (will be av_strduped or added as a new key depending on flags). + * Passing a NULL value will cause an existing entry to be deleted. + * + * @return >= 0 on success otherwise an error code <0 */ int av_dict_set(AVDictionary **pm, const char *key, const char *value, int flags); /** - * Convenience wrapper for av_dict_set that converts the value to a string + * Convenience wrapper for av_dict_set() that converts the value to a string * and stores it. * - * Note: If AV_DICT_DONT_STRDUP_KEY is set, key will be freed on error. + * Note: If ::AV_DICT_DONT_STRDUP_KEY is set, key will be freed on error. */ int av_dict_set_int(AVDictionary **pm, const char *key, int64_t value, int flags); @@ -167,14 +180,15 @@ int av_dict_set_int(AVDictionary **pm, const char *key, int64_t value, int flags * In case of failure, all the successfully set entries are stored in * *pm. You may need to manually free the created dictionary. * - * @param key_val_sep a 0-terminated list of characters used to separate + * @param key_val_sep A 0-terminated list of characters used to separate * key from value - * @param pairs_sep a 0-terminated list of characters used to separate + * @param pairs_sep A 0-terminated list of characters used to separate * two pairs from each other - * @param flags flags to use when adding to dictionary. - * AV_DICT_DONT_STRDUP_KEY and AV_DICT_DONT_STRDUP_VAL + * @param flags Flags to use when adding to the dictionary. + * ::AV_DICT_DONT_STRDUP_KEY and ::AV_DICT_DONT_STRDUP_VAL * are ignored since the key/value tokens will always * be duplicated. + * * @return 0 on success, negative AVERROR code on failure */ int av_dict_parse_string(AVDictionary **pm, const char *str, @@ -183,11 +197,14 @@ int av_dict_parse_string(AVDictionary **pm, const char *str, /** * Copy entries from one AVDictionary struct into another. - * @param dst pointer to a pointer to a AVDictionary struct. If *dst is NULL, - * this function will allocate a struct for you and put it in *dst - * @param src pointer to source AVDictionary struct - * @param flags flags to use when setting entries in *dst - * @note metadata is read using the AV_DICT_IGNORE_SUFFIX flag + * + * @note Metadata is read using the ::AV_DICT_IGNORE_SUFFIX flag + * + * @param dst Pointer to a pointer to a AVDictionary struct to copy into. If *dst is NULL, + * this function will allocate a struct for you and put it in *dst + * @param src Pointer to the source AVDictionary struct to copy items from. + * @param flags Flags to use when setting entries in *dst + * * @return 0 on success, negative AVERROR code on failure. If dst was allocated * by this function, callers should free the associated memory. */ @@ -206,13 +223,15 @@ void av_dict_free(AVDictionary **m); * Such string may be passed back to av_dict_parse_string(). * @note String is escaped with backslashes ('\'). * - * @param[in] m dictionary + * @warning Separators cannot be neither '\\' nor '\0'. They also cannot be the same. + * + * @param[in] m The dictionary * @param[out] buffer Pointer to buffer that will be allocated with string containg entries. * Buffer must be freed by the caller when is no longer needed. - * @param[in] key_val_sep character used to separate key from value - * @param[in] pairs_sep character used to separate two pairs from each other + * @param[in] key_val_sep Character used to separate key from value + * @param[in] pairs_sep Character used to separate two pairs from each other + * * @return >= 0 on success, negative on error - * @warning Separators cannot be neither '\\' nor '\0'. They also cannot be the same. */ int av_dict_get_string(const AVDictionary *m, char **buffer, const char key_val_sep, const char pairs_sep);