Function flac_sys::FLAC__metadata_simple_iterator_set_block

pub unsafe extern "C" fn FLAC__metadata_simple_iterator_set_block(
    iterator: *mut FLAC__Metadata_SimpleIterator, 
    block: *mut FLAC__StreamMetadata, 
    use_padding: FLAC__bool
) -> FLAC__bool

Write a block back to the FLAC file. This function tries to be as efficient as possible; how the block is actually written is shown by the following:

Existing block is a STREAMINFO block and the new block is a STREAMINFO block: the new block is written in place. Make sure you know what you're doing when changing the values of a STREAMINFO block.

Existing block is a STREAMINFO block and the new block is a not a STREAMINFO block: this is an error since the first block must be a STREAMINFO block. Returns \c false without altering the file.

Existing block is not a STREAMINFO block and the new block is a STREAMINFO block: this is an error since there may be only one STREAMINFO block. Returns \c false without altering the file.

Existing block and new block are the same length: the existing block will be replaced by the new block, written in place.

Existing block is longer than new block: if use_padding is \c true, the existing block will be overwritten in place with the new block followed by a PADDING block, if possible, to make the total size the same as the existing block. Remember that a padding block requires at least four bytes so if the difference in size between the new block and existing block is less than that, the entire file will have to be rewritten, using the new block's exact size. If use_padding is \c false, the entire file will be rewritten, replacing the existing block by the new block.

Existing block is shorter than new block: if use_padding is \c true, the function will try and expand the new block into the following PADDING block, if it exists and doing so won't shrink the PADDING block to less than 4 bytes. If there is no following PADDING block, or it will shrink to less than 4 bytes, or use_padding is \c false, the entire file is rewritten, replacing the existing block with the new block. Note that in this case any following PADDING block is preserved as is.

After writing the block, the iterator will remain in the same place, i.e. pointing to the new block.

\param iterator A pointer to an existing initialized iterator. \param block The block to set. \param use_padding See above. \assert \code iterator != NULL \endcode \a iterator has been successfully initialized with FLAC__metadata_simple_iterator_init() \code block != NULL \endcode \retval FLAC__bool \c true if successful, else \c false.