diff --git a/c-api/refcounting.po b/c-api/refcounting.po index 7f9b3153dd..855b69a842 100644 --- a/c-api/refcounting.po +++ b/c-api/refcounting.po @@ -8,8 +8,8 @@ msgid "" msgstr "" "Project-Id-Version: Python 3.12\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2023-07-24 00:03+0000\n" -"PO-Revision-Date: 2023-07-01 14:19+0800\n" +"POT-Creation-Date: 2023-08-14 22:55+0800\n" +"PO-Revision-Date: 2023-08-06 14:19+0800\n" "Last-Translator: Matt Wang \n" "Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-" "tw)\n" @@ -36,26 +36,55 @@ msgstr "取得物件 *o* 的參照計數。" #: ../../c-api/refcounting.rst:18 msgid "" -"Use the :c:func:`Py_SET_REFCNT()` function to set an object reference count." +"Note that the returned value may not actually reflect how many references to " +"the object are actually held. For example, some objects are \"immortal\" " +"and have a very high refcount that does not reflect the actual number of " +"references. Consequently, do not rely on the returned value to be accurate, " +"other than a value of 0 or 1." msgstr "" +"請注意,回傳的值可能實際上並不反映實際保存了多少對該物件的參照。例如,某些物" +"件是「不滅的 (immortal)」,並且具有非常高的參照計數,不能反映實際的參照數量。" +"因此,除了 0 或 1 以外,不要依賴回傳值的準確性。" -#: ../../c-api/refcounting.rst:20 +#: ../../c-api/refcounting.rst:24 +msgid "" +"Use the :c:func:`Py_SET_REFCNT()` function to set an object reference count." +msgstr "使用 :c:func:`Py_SET_REFCNT()` 函式設定物件參照計數。" + +#: ../../c-api/refcounting.rst:26 msgid "The parameter type is no longer :c:expr:`const PyObject*`." -msgstr "" +msgstr "參數型別不再是 :c:expr:`const PyObject*`。" -#: ../../c-api/refcounting.rst:23 +#: ../../c-api/refcounting.rst:29 msgid ":c:func:`Py_REFCNT()` is changed to the inline static function." -msgstr "" +msgstr ":c:func:`Py_REFCNT()` 更改為行內靜態函式 (inline static function)。" -#: ../../c-api/refcounting.rst:29 +#: ../../c-api/refcounting.rst:35 msgid "Set the object *o* reference counter to *refcnt*." msgstr "設定物件 *o* 的參照計數。" -#: ../../c-api/refcounting.rst:36 -msgid "Increment the reference count for object *o*." -msgstr "增加物件 *o* 的參照計數。" +#: ../../c-api/refcounting.rst:37 +msgid "" +"Note that this function has no effect on `immortal `_ objects." +msgstr "" +"請注意,此函式對\\ `不滅的 `_\\ 物件沒有影" +"響。" + +#: ../../c-api/refcounting.rst:43 ../../c-api/refcounting.rst:65 +#: ../../c-api/refcounting.rst:142 +msgid "Immortal objects are not modified." +msgstr "不滅的物件不會被修改。" + +#: ../../c-api/refcounting.rst:49 +msgid "" +"Indicate taking a new :term:`strong reference` to object *o*, indicating it " +"is in use and should not be destroyed." +msgstr "" +"代表取得對於物件 *o* 的新\\ :term:`強參照 `,即它正在使用且" +"不應被銷毀。" -#: ../../c-api/refcounting.rst:38 +#: ../../c-api/refcounting.rst:52 msgid "" "This function is usually used to convert a :term:`borrowed reference` to a :" "term:`strong reference` in-place. The :c:func:`Py_NewRef` function can be " @@ -65,7 +94,11 @@ msgstr "" "換為\\ :term:`強參照 `。:c:func:`Py_NewRef` 函式可用於建立" "新的\\ :term:`強參照 `。" -#: ../../c-api/refcounting.rst:42 +#: ../../c-api/refcounting.rst:56 +msgid "When done using the object, release it by calling :c:func:`Py_DECREF`." +msgstr "使用完該物件後,透過呼叫 :c:func:`Py_DECREF` 來釋放它。" + +#: ../../c-api/refcounting.rst:58 msgid "" "The object must not be ``NULL``; if you aren't sure that it isn't ``NULL``, " "use :c:func:`Py_XINCREF`." @@ -73,34 +106,44 @@ msgstr "" "該物件不能為 ``NULL``;如果你不確定它不是 ``NULL``,請使用 :c:func:" "`Py_XINCREF`。" -#: ../../c-api/refcounting.rst:48 +#: ../../c-api/refcounting.rst:61 ../../c-api/refcounting.rst:127 msgid "" -"Increment the reference count for object *o*. The object may be ``NULL``, " -"in which case the macro has no effect." +"Do not expect this function to actually modify *o* in any way. For at least " +"`some objects `_, this function has no " +"effect." msgstr "" -"增加物件 *o* 的參照計數。該物件可能是 ``NULL``,在這種情況下巨集不起作用。" +"不要期望此函式會以任何方式實際修改 *o*,至少對於\\ `某些物件 `_\\ 來說,此函式沒有任何效果。" -#: ../../c-api/refcounting.rst:51 +#: ../../c-api/refcounting.rst:71 +msgid "" +"Similar to :c:func:`Py_INCREF`, but the object *o* can be ``NULL``, in which " +"case this has no effect." +msgstr "" +"與 :c:func:`Py_INCREF` 類似,但物件 *o* 可以為 ``NULL``,在這種情況下這就不會" +"有任何效果。" + +#: ../../c-api/refcounting.rst:74 msgid "See also :c:func:`Py_XNewRef`." msgstr "另請見 :c:func:`Py_XNewRef`。" -#: ../../c-api/refcounting.rst:56 +#: ../../c-api/refcounting.rst:79 msgid "" -"Create a new :term:`strong reference` to an object: increment the reference " -"count of the object *o* and return the object *o*." +"Create a new :term:`strong reference` to an object: call :c:func:`Py_INCREF` " +"on *o* and return the object *o*." msgstr "" -"建立對物件的新\\ :term:`強參照 `:增加物件 *o* 的參照計數並" -"回傳物件 *o*。" +"建立對物件的新\\ :term:`強參照 `:於 *o* 呼叫 :c:func:" +"`Py_INCREF` 並回傳物件 *o*。" -#: ../../c-api/refcounting.rst:59 +#: ../../c-api/refcounting.rst:82 msgid "" "When the :term:`strong reference` is no longer needed, :c:func:`Py_DECREF` " -"should be called on it to decrement the object reference count." +"should be called on it to release the reference." msgstr "" "當不再需要\\ :term:`強參照 `\\ 時,應對其呼叫 :c:func:" -"`Py_DECREF` 以減少物件參照計數。" +"`Py_DECREF` 以釋放該參照。" -#: ../../c-api/refcounting.rst:62 +#: ../../c-api/refcounting.rst:85 msgid "" "The object *o* must not be ``NULL``; use :c:func:`Py_XNewRef` if *o* can be " "``NULL``." @@ -108,52 +151,52 @@ msgstr "" "物件 *o* 不能為 ``NULL``;如果 *o* 可以為 ``NULL``,則使用 :c:func:" "`Py_XNewRef`。" -#: ../../c-api/refcounting.rst:65 +#: ../../c-api/refcounting.rst:88 msgid "For example::" -msgstr "" -"舉例來說:\n" -"\n" -"::" +msgstr "舉例來說: ::" -#: ../../c-api/refcounting.rst:70 +#: ../../c-api/refcounting.rst:93 msgid "can be written as::" -msgstr "" -"可以寫成:\n" -"\n" -"::" +msgstr "可以寫成: ::" -#: ../../c-api/refcounting.rst:74 +#: ../../c-api/refcounting.rst:97 msgid "See also :c:func:`Py_INCREF`." -msgstr "另請參閱 :c:func:`Py_INCREF`\\ 。" +msgstr "另請參閱 :c:func:`Py_INCREF`。" -#: ../../c-api/refcounting.rst:81 +#: ../../c-api/refcounting.rst:104 msgid "Similar to :c:func:`Py_NewRef`, but the object *o* can be NULL." msgstr "與 :c:func:`Py_NewRef` 類似,但物件 *o* 可以為 NULL。" -#: ../../c-api/refcounting.rst:83 +#: ../../c-api/refcounting.rst:106 msgid "If the object *o* is ``NULL``, the function just returns ``NULL``." msgstr "如果物件 *o* 為 ``NULL``,則該函式僅回傳 ``NULL``。" -#: ../../c-api/refcounting.rst:90 -msgid "Decrement the reference count for object *o*." -msgstr "減少物件 *o* 的參照計數。" +#: ../../c-api/refcounting.rst:113 +msgid "" +"Release a :term:`strong reference` to object *o*, indicating the reference " +"is no longer used." +msgstr "" +"釋放一個對物件 *o* 的\\ :term:`強參照 `,代表該參照不會再被" +"使用。" -#: ../../c-api/refcounting.rst:92 +#: ../../c-api/refcounting.rst:116 msgid "" -"If the reference count reaches zero, the object's type's deallocation " -"function (which must not be ``NULL``) is invoked." +"Once the last :term:`strong reference` is released (i.e. the object's " +"reference count reaches 0), the object's type's deallocation function (which " +"must not be ``NULL``) is invoked." msgstr "" -"如果參照計數達到零,則調用物件之型別的釋放函式 (deallocation function)(不得" -"為 ``NULL``)。" +"如果最後一個\\ :term:`強參照 `\\ 被釋放(即物件的參照計數達" +"到零),則觸發物件之型別的釋放函式 (deallocation function)(不得為 " +"``NULL``\\ )。" -#: ../../c-api/refcounting.rst:95 +#: ../../c-api/refcounting.rst:121 msgid "" "This function is usually used to delete a :term:`strong reference` before " "exiting its scope." msgstr "" "此函式通常用於在退出作用域之前刪除\\ :term:`強參照 `。" -#: ../../c-api/refcounting.rst:98 +#: ../../c-api/refcounting.rst:124 msgid "" "The object must not be ``NULL``; if you aren't sure that it isn't ``NULL``, " "use :c:func:`Py_XDECREF`." @@ -161,7 +204,7 @@ msgstr "" "該物件不能為 ``NULL``;如果你不確定它不是 ``NULL``,請改用 :c:func:" "`Py_XDECREF`。" -#: ../../c-api/refcounting.rst:103 +#: ../../c-api/refcounting.rst:133 msgid "" "The deallocation function can cause arbitrary Python code to be invoked (e." "g. when a class instance with a :meth:`~object.__del__` method is " @@ -173,103 +216,105 @@ msgid "" "object in a temporary variable, update the list data structure, and then " "call :c:func:`Py_DECREF` for the temporary variable." msgstr "" -"釋放函式可以導致任意 Python 程式碼被調用(例如,當釋放具有 :meth:`~object.__del__` 方" -"法的類別實例時)。雖然此類程式碼中的例外不會被傳遞出來,但​​執行的程式碼可以自" -"由存取所有 Python 全域變數。這意味著在調用 :c:func:`Py_DECREF` 之前,可從全域" -"變數存取的任何物件都應處於一致狀態。例如,從 list 中刪除物件的程式碼應將已刪" -"除物件的參照複製到臨時變數中,更新 list 資料結構,然後為臨時變數呼叫 :c:func:" -"`Py_DECREF`。" - -#: ../../c-api/refcounting.rst:115 +"釋放函式可以導致任意 Python 程式碼被調用(例如,當釋放具有 :meth:`~object." +"__del__` 方法的類別實例時)。雖然此類程式碼中的例外不會被傳遞出來,但​​執行的程" +"式碼可以自由存取所有 Python 全域變數。這意味著在調用 :c:func:`Py_DECREF` 之" +"前,可從全域變數存取的任何物件都應處於一致狀態。例如,從 list 中刪除物件的程" +"式碼應將已刪除物件的參照複製到臨時變數中,更新 list 資料結構,然後為臨時變數" +"呼叫 :c:func:`Py_DECREF`。" + +#: ../../c-api/refcounting.rst:148 msgid "" -"Decrement the reference count for object *o*. The object may be ``NULL``, " -"in which case the macro has no effect; otherwise the effect is the same as " -"for :c:func:`Py_DECREF`, and the same warning applies." +"Similar to :c:func:`Py_DECREF`, but the object *o* can be ``NULL``, in which " +"case this has no effect. The same warning from :c:func:`Py_DECREF` applies " +"here as well." msgstr "" -"減少物件 *o* 的參照計數。該物件可能是 ``NULL``,在這種情況下巨集不起作用;否" -"則效果與 :c:func:`Py_DECREF` 相同,且使得應用了相同的警告。" +"和 :c:func:`Py_DECREF` 類似,但該物件可以是 ``NULL``,在這種情況下巨集不起作" +"用。在這裡也會出現與 :c:func:`Py_DECREF` 相同的警告。" -#: ../../c-api/refcounting.rst:122 +#: ../../c-api/refcounting.rst:155 msgid "" -"Decrement the reference count for object *o*. The object may be ``NULL``, " -"in which case the macro has no effect; otherwise the effect is the same as " -"for :c:func:`Py_DECREF`, except that the argument is also set to ``NULL``. " -"The warning for :c:func:`Py_DECREF` does not apply with respect to the " -"object passed because the macro carefully uses a temporary variable and sets " -"the argument to ``NULL`` before decrementing its reference count." +"Release a :term:`strong reference` for object *o*. The object may be " +"``NULL``, in which case the macro has no effect; otherwise the effect is the " +"same as for :c:func:`Py_DECREF`, except that the argument is also set to " +"``NULL``. The warning for :c:func:`Py_DECREF` does not apply with respect " +"to the object passed because the macro carefully uses a temporary variable " +"and sets the argument to ``NULL`` before releasing the reference." msgstr "" -"減少物件 *o* 的參照計數。該物件可能是 ``NULL``,在這種情況下巨集不起作用;否" -"則,效果與 :c:func:`Py_DECREF` 相同,只是引數也設定為 ``NULL``。:c:func:" -"`Py_DECREF` 的警告不適用於傳遞的物件,因為巨集在遞減其參照計數之前小心地使用" -"臨時變數並將參數設定為 ``NULL``。" +"釋放對於物件 *o* 的\\ :term:`強參照 `。該物件可能是 " +"``NULL``,在這種情況下巨集不起作用;否則,效果與 :c:func:`Py_DECREF` 相同,除" +"非引數也設定為 ``NULL``。:c:func:`Py_DECREF` 的警告不適用於傳遞的物件,因為巨" +"集在釋放其參照之前小心地使用臨時變數並將引數設定為 ``NULL``。" -#: ../../c-api/refcounting.rst:129 +#: ../../c-api/refcounting.rst:163 msgid "" -"It is a good idea to use this macro whenever decrementing the reference " -"count of an object that might be traversed during garbage collection." +"It is a good idea to use this macro whenever releasing a reference to an " +"object that might be traversed during garbage collection." msgstr "" -"每當要減少垃圾收集期間可能被遍歷到之物件的參照計數時,使用此巨集是個好主意。" +"每當要釋放垃圾回收 (garbage collection) 期間可能被遍歷到之對於物件的參照時," +"使用此巨集是個好主意。" -#: ../../c-api/refcounting.rst:132 +#: ../../c-api/refcounting.rst:166 msgid "" "The macro argument is now only evaluated once. If the argument has side " "effects, these are no longer duplicated." msgstr "" +"巨集引數現在僅會被求值 (evaluate) 一次。如果引數有其他副作用,則不再重複作" +"用。" -#: ../../c-api/refcounting.rst:139 +#: ../../c-api/refcounting.rst:173 msgid "" -"Increment the reference count for object *o*. A function version of :c:func:" -"`Py_XINCREF`. It can be used for runtime dynamic embedding of Python." +"Indicate taking a new :term:`strong reference` to object *o*. A function " +"version of :c:func:`Py_XINCREF`. It can be used for runtime dynamic " +"embedding of Python." msgstr "" -"增加物件 *o* 的參照計數。:c:func:`Py_XINCREF` 的函式版本。它可用於 Python 的" -"執行環境動態嵌入。" +"代表取得對於物件 *o* 的\\ :term:`強參照 `。:c:func:" +"`Py_XINCREF` 的函式版本。它可用於 Python 的 runtime 動態嵌入。" -#: ../../c-api/refcounting.rst:145 +#: ../../c-api/refcounting.rst:180 msgid "" -"Decrement the reference count for object *o*. A function version of :c:func:" -"`Py_XDECREF`. It can be used for runtime dynamic embedding of Python." +"Release a :term:`strong reference` to object *o*. A function version of :c:" +"func:`Py_XDECREF`. It can be used for runtime dynamic embedding of Python." msgstr "" -"減少物件 *o* 的參照計數。:c:func:`Py_XDECREF` 的函式版本。它可用於 Python 的" -"執行環境動態嵌入。" +"釋放對物件 *o* 的\\ :term:`強參照 `。:c:func:`Py_XDECREF` " +"的函式版本。它可用於 Python 的 runtime 動態嵌入。" -#: ../../c-api/refcounting.rst:151 +#: ../../c-api/refcounting.rst:187 msgid "" -"Macro safely decrementing the `dst` reference count and setting `dst` to " -"`src`." +"Macro safely releasing a :term:`strong reference` to object *dst* and " +"setting *dst* to *src*." msgstr "" +"巨集安全地釋放對於物件 *dst* 的\\ :term:`強參照 `\\ 並將 " +"*dst* 設定為 *src*。" -#: ../../c-api/refcounting.rst:154 +#: ../../c-api/refcounting.rst:190 msgid "As in case of :c:func:`Py_CLEAR`, \"the obvious\" code can be deadly::" -msgstr "" +msgstr "與 :c:func:`Py_CLEAR` 的情況一樣,「明顯的」程式碼可能是致命的: ::" -#: ../../c-api/refcounting.rst:159 +#: ../../c-api/refcounting.rst:195 msgid "The safe way is::" -msgstr "" +msgstr "安全的方法是: ::" -#: ../../c-api/refcounting.rst:163 +#: ../../c-api/refcounting.rst:199 msgid "" -"That arranges to set `dst` to `src` _before_ decrementing reference count of " -"*dst* old value, so that any code triggered as a side-effect of `dst` " -"getting torn down no longer believes `dst` points to a valid object." +"That arranges to set *dst* to *src* _before_ releasing the reference to the " +"old value of *dst*, so that any code triggered as a side-effect of *dst* " +"getting torn down no longer believes *dst* points to a valid object." msgstr "" +"這會在釋放對 *dst* 舊值的參照\\ _之前_\\ 將 *dst* 設定為 *src*,使得因 *dst* " +"被拆除而觸發的任何副作用 (side-effect) 之程式碼不會相信 *dst* 是指向一個有效" +"物件。" -#: ../../c-api/refcounting.rst:169 ../../c-api/refcounting.rst:181 +#: ../../c-api/refcounting.rst:206 ../../c-api/refcounting.rst:218 msgid "" "The macro arguments are now only evaluated once. If an argument has side " "effects, these are no longer duplicated." -msgstr "" +msgstr "巨集引數現在僅會被求值一次。如果引數有其他副作用,則不再重複作用。" -#: ../../c-api/refcounting.rst:176 +#: ../../c-api/refcounting.rst:213 msgid "" "Variant of :c:macro:`Py_SETREF` macro that uses :c:func:`Py_XDECREF` instead " "of :c:func:`Py_DECREF`." msgstr "" - -#~ msgid "" -#~ "The following functions or macros are only for use within the interpreter " -#~ "core: :c:func:`_Py_Dealloc`, :c:func:`_Py_ForgetReference`, :c:func:" -#~ "`_Py_NewReference`, as well as the global variable :c:data:`_Py_RefTotal`." -#~ msgstr "" -#~ "以下函式或巨集僅在直譯器核心內使用::c:func:`_Py_Dealloc`、:c:func:" -#~ "`_Py_ForgetReference`、:c:func:`_Py_NewReference` 以及全域變數 :c:data:" -#~ "`_Py_RefTotal`。" +":c:macro:`Py_SETREF` 巨集的變體,請改用 :c:func:`Py_XDECREF` 而非 :c:func:" +"`Py_DECREF`。"