---

10.13.4 po_message_t API ¶

Data Type: po_message_t ¶

This is a pointer type that refers to a message of a PO file, including its translation.

Function: po_message_t po_message_create (void) ¶

Returns a freshly constructed message. To finish initializing the message, you must set the msgid and msgstr. It must be inserted into a file to manage its memory, as there is no po_message_free available to the user of the library.

The following functions access details of a po_message_t. Recall that the results are valid as long as the file handle is valid.

Function: const char * po_message_msgctxt (po_message_t message) ¶

The po_message_msgctxt function returns the msgctxt, the context of message. Returns NULL for a message not restricted to a context.

Function: void po_message_set_msgctxt (po_message_t message, const char *msgctxt) ¶

The po_message_set_msgctxt function changes the msgctxt, the context of the message, to the value provided through msgctxt. The value NULL removes the restriction.

Function: const char * po_message_msgid (po_message_t message) ¶

The po_message_msgid function returns the msgid (untranslated English string) of message. This is guaranteed to be non-NULL.

Function: void po_message_set_msgid (po_message_t message, const char *msgid) ¶

The po_message_set_msgid function changes the msgid (untranslated English string) of message to the value provided through msgid, a non-NULL string.

Function: const char * po_message_msgid_plural (po_message_t message) ¶

The po_message_msgid_plural function returns the msgid_plural (untranslated English plural string) of message, a message with plurals, or NULL for a message without plural.

Function: void po_message_set_msgid_plural (po_message_t message, const char *msgid_plural) ¶

The po_message_set_msgid_plural function changes the msgid_plural (untranslated English plural string) of a message to the value provided through msgid_plural, or removes the plurals if NULL is provided as msgid_plural.

Function: const char * po_message_msgstr (po_message_t message) ¶

The po_message_msgstr function returns the msgstr (translation) of message. For an untranslated message, the return value is an empty string.

Function: void po_message_set_msgstr (po_message_t message, const char *msgstr) ¶

The po_message_set_msgstr function changes the msgstr (translation) of message to the value provided through msgstr, a non-NULL string.

Function: const char * po_message_msgstr_plural (po_message_t message, int index) ¶

The po_message_msgstr_plural function returns the msgstr[index] of message, a message with plurals, or NULL when the index is out of range or for a message without plural.

Function: void po_message_set_msgstr_plural (po_message_t message, int index, const char *msgstr_plural) ¶

The po_message_set_msgstr_plural function changes the msgstr[index] of message, a message with plurals, to the value provided through msgstr_plural. message must be a message with plurals. Use NULL as the value of msgstr_plural with index pointing to the last element to reduce the number of plural forms.

Function: const char * po_message_comments (po_message_t message) ¶

The po_message_comments function returns the comments of message, a multiline string, ending in a newline, or a non-NULL empty string.

Function: void po_message_set_comments (po_message_t message, const char *comments) ¶

The po_message_set_comments function changes the comments of message to the value comments, a multiline string, ending in a newline, or a non-NULL empty string.

Function: const char * po_message_extracted_comments (po_message_t message) ¶

The po_message_extracted_comments function returns the extracted comments of message, a multiline string, ending in a newline, or a non-NULL empty string.

Function: void po_message_set_extracted_comments (po_message_t message, const char *extracted_comments) ¶

The po_message_set_extracted_comments function changes the comments of message to the value extracted_comments, a multiline string, ending in a newline, or a non-NULL empty string.

Function: const char * po_message_prev_msgctxt (po_message_t message) ¶

The po_message_prev_msgctxt function returns the previous msgctxt, the previous context of message. Return NULL for a message that does not have a previous context.

Function: void po_message_set_prev_msgctxt (po_message_t message, const char *prev_msgctxt) ¶

The po_message_set_prev_msgctxt function changes the previous msgctxt, the context of the message, to the value provided through prev_msgctxt. The value NULL removes the stored previous msgctxt.

Function: const char * po_message_prev_msgid (po_message_t message) ¶

The po_message_prev_msgid function returns the previous msgid (untranslated English string) of message, or NULL if there is no previous msgid stored.

Function: void po_message_set_prev_msgid (po_message_t message, const char *prev_msgid) ¶

The po_message_set_prev_msgid function changes the previous msgid (untranslated English string) of message to the value provided through prev_msgid, or removes the message when it is NULL.

Function: const char * po_message_prev_msgid_plural (po_message_t message) ¶

The po_message_prev_msgid_plural function returns the previous msgid_plural (untranslated English plural string) of message, a message with plurals, or NULL for a message without plural without any stored previous msgid_plural.

Function: void po_message_set_prev_msgid_plural (po_message_t message, const char *prev_msgid_plural) ¶

The po_message_set_prev_msgid_plural function changes the previous msgid_plural (untranslated English plural string) of a message to the value provided through prev_msgid_plural, or removes the stored previous msgid_plural if NULL is provided as prev_msgid_plural.

Function: int po_message_is_obsolete (po_message_t message) ¶

The po_message_is_obsolete function returns true when message is marked as obsolete.

Function: void po_message_set_obsolete (po_message_t message, int obsolete) ¶

The po_message_set_obsolete function changes the obsolete mark of message.

Function: int po_message_is_fuzzy (po_message_t message) ¶

The po_message_is_fuzzy function returns true when message is marked as fuzzy.

Function: void po_message_set_fuzzy (po_message_t message, int fuzzy) ¶

The po_message_set_fuzzy function changes the fuzzy mark of message.

Function: int po_message_has_workflow_flag (po_message_t message, const char *workflow_flag) ¶

The po_message_has_workflow_flag function returns true when message is marked with a given workflow flag.

When the argument workflow_flag is "fuzzy", this function corresponds to the po_message_is_fuzzy function.

Function: void po_message_set_workflow_flag (po_message_t message, const char *workflow_flag, int value) ¶

The po_message_set_workflow_flag function changes a given workflow flag on message: If the value argument is non-zero, it sets it. If the value argument is zero, it unsets it.

When the argument workflow_flag is "fuzzy", this function corresponds to the po_message_set_fuzzy function.

Function: po_flag_iterator_t po_message_workflow_flags_iterator (po_message_t message) ¶

The po_message_workflow_flags_iterator function returns an iterator across the workflow flags of message. This includes the "fuzzy" flag. This iterator returns the workflow flags set on message, one by one, through the function po_flag_next. When done, you should free the iterator, through the function po_flag_iterator_free.

Function: int po_message_is_format (po_message_t message, const char *format_type) ¶

The po_message_is_format function returns true when the message is marked as being a format string of format_type.

Function: int po_message_get_format (po_message_t message, const char *format_type) ¶

The po_message_get_format function returns an indicator whether the message is marked as being a format string of format_type or the opposite (no-format_type). More precisely, it returns 1 if the format_type mark is set, 0 if the no-format_type mark is set, or -1 of neither the mark nor the opposite mark is set.

Function: void po_message_set_format (po_message_t message, const char *format_type, int value) ¶

The po_message_set_format function changes the format string mark of the message for the format_type provided. Pass value = 1 to assert the format string mark (leading to e.g. ‘c-format’), value = 0 to assert the opposite (leading to e.g. ‘no-c-format’), or value = -1 to remove the format string mark and its opposite.

Function: int po_message_has_sticky_flag (po_message_t message, const char *sticky_flag) ¶

The po_message_has_sticky_flag function returns true when message is marked with a given sticky flag.

This function is a generalization of the po_message_is_format and po_message_get_format format functions.

Function: void po_message_set_sticky_flag (po_message_t message, const char *sticky_flag, int value) ¶

The po_message_set_sticky_flag function changes a given sticky flag on message: If the value argument is non-zero, it sets it. If the value argument is zero, it unsets it.

This function is a generalization of the po_message_set_format function.

Note that a message cannot have the sticky flags language-format and no-language-format at the same time. Therefore, setting the language-format flag for some language has the side effect of unsetting the no-language-format flag, and vice versa.

Function: po_flag_iterator_t po_message_sticky_flags_iterator (po_message_t message) ¶

The po_message_sticky_flags_iterator function returns an iterator across the sticky flags of message. This includes the various language-format and no-language-format flags, as well as the no-wrap flag. It does not include the "range", because that is not a flag. This iterator returns the sticky flags set on message, one by one, through the function po_flag_next. When done, you should free the iterator, through the function po_flag_iterator_free.

Function: int po_message_is_range (po_message_t message, int *minp, int *maxp) ¶

The po_message_is_range function returns true when the message has a numeric range set, and stores the minimum and maximum value in the locations pointed by minp and maxp respectively.

Function: void po_message_set_range (po_message_t message, int min, int max) ¶

The po_message_set_range function changes the numeric range of the message. min and max must be non-negative, with min < max. Use min and max with value -1 to remove the numeric range of message.