Replaces comments in a VORBIS_COMMENT block with a new one.
For convenience, a trailing NUL is added to the entry if it doesn't have
one already.
Depending on the the value of \a all, either all or just the first comment
whose field name(s) match the given entry's name will be replaced by the
given entry. If no comments match, \a entry will simply be appended.
If \a copy is \c true, a copy of the entry is stored; otherwise, the object
takes ownership of the \c entry.entry pointer.
\note If this function returns \c false, the caller still owns the
pointer.
\param object A pointer to an existing VORBIS_COMMENT object.
\param entry The comment to insert.
\param all If \c true, all comments whose field name matches
\a entry's field name will be removed, and \a entry will
be inserted at the position of the first matching
comment. If \c false, only the first comment whose
field name matches \a entry's field name will be
replaced with \a entry.
\param copy See above.
\assert
\code object != NULL \endcode
\code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
\code (entry.entry != NULL && entry.length > 0) ||
(entry.entry == NULL && entry.length == 0 && copy == false) \endcode
\retval FLAC__bool
\c false if memory allocation fails or \a entry does not comply with the
Vorbis comment specification, else \c true.
Replaces comments in a VORBIS_COMMENT block with a new one.
For convenience, a trailing NUL is added to the entry if it doesn't have one already.
Depending on the the value of \a all, either all or just the first comment whose field name(s) match the given entry's name will be replaced by the given entry. If no comments match, \a entry will simply be appended.
If \a copy is \c true, a copy of the entry is stored; otherwise, the object takes ownership of the \c entry.entry pointer.
\note If this function returns \c false, the caller still owns the pointer.
\param object A pointer to an existing VORBIS_COMMENT object. \param entry The comment to insert. \param all If \c true, all comments whose field name matches \a entry's field name will be removed, and \a entry will be inserted at the position of the first matching comment. If \c false, only the first comment whose field name matches \a entry's field name will be replaced with \a entry. \param copy See above. \assert \code object != NULL \endcode \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode \code (entry.entry != NULL && entry.length > 0) || (entry.entry == NULL && entry.length == 0 && copy == false) \endcode \retval FLAC__bool \c false if memory allocation fails or \a entry does not comply with the Vorbis comment specification, else \c true.