File: gettext.info,  Node: po_message_t API,  Next: PO Header Entry API,  Prev: po_message_iterator_t API,  Up: libgettextpo

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.