Insert a comment in a VORBIS_COMMENT block at the given index.
For convenience, a trailing NUL is added to the entry if it doesn't have
one already.
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 comment_num The index at which to insert the comment. The comments
at and after \a comment_num move right one position.
To append a comment to the end, set \a comment_num to
\c object->data.vorbis_comment.num_comments .
\param entry The comment to insert.
\param copy See above.
\assert
\code object != NULL \endcode
\code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode
\code object->data.vorbis_comment.num_comments >= comment_num \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.
Insert a comment in a VORBIS_COMMENT block at the given index.
For convenience, a trailing NUL is added to the entry if it doesn't have one already.
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 comment_num The index at which to insert the comment. The comments at and after \a comment_num move right one position. To append a comment to the end, set \a comment_num to \c object->data.vorbis_comment.num_comments . \param entry The comment to insert. \param copy See above. \assert \code object != NULL \endcode \code object->type == FLAC__METADATA_TYPE_VORBIS_COMMENT \endcode \code object->data.vorbis_comment.num_comments >= comment_num \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.