Leave metadata items untouched if resize function fails

2 files changed, 21 insertions, 5 deletions

diff --git a/include/FLAC/all.h b/include/FLAC/all.h
index ee6e132c..8c6cdc3c 100644
--- a/include/FLAC/all.h
+++ b/include/FLAC/all.h
@@ -365,10 +365,13 @@
  *
  * \section porting_1_3_4_to_1_4_0_summary Summary
  *
- * Between FLAC 1.3.4 and FLAC 1.4.0, there have three breaking changes
+ * Between FLAC 1.3.4 and FLAC 1.4.0, there have four breaking changes
  * - the function get_client_data_from_decoder has been renamed to
  *   FLAC__get_decoder_client_data
  * - some data types in the FLAC__Frame struct have changed
+ * - all functions resizing metadata blocks now return the object
+ *   untouched if memory allocation fails, whereas previously the
+ *   handling varied and was more or less undefined
  * - all functions accepting a filename now take UTF-8 encoded filenames
  *   on Windows instead of filenames in the current codepage
  *
@@ -398,6 +401,15 @@
  * data_type, which clarifies whether the FLAC__int32 or FLAC__int64
  * array is in use.
  *
+ * Furthermore, the following functions now return the object untouched
+ * if memory allocation fails, whereas previously the handling varied
+ * and was more or less undefined
+ *
+ * - FLAC__metadata_object_seektable_resize_points
+ * - FLAC__metadata_object_vorbiscomment_resize_comments
+ * - FLAC__metadata_object_cuesheet_track_resize_indices
+ * - FLAC__metadata_object_cuesheet_resize_tracks
+ *
  * The last breaking change is that all API functions taking a filename
  * as an argument now, on Windows, must be supplied with that filename
  * in the UTF-8 character encoding instead of using the current code
diff --git a/include/FLAC/metadata.h b/include/FLAC/metadata.h
index aa369054..bf1bffe4 100644
--- a/include/FLAC/metadata.h
+++ b/include/FLAC/metadata.h
@@ -1398,7 +1398,8 @@ FLAC_API FLAC__bool FLAC__metadata_object_application_set_data(FLAC__StreamMetad
 /** Resize the seekpoint array.
  *
  *  If the size shrinks, elements will truncated; if it grows, new placeholder
- *  points will be added to the end.
+ *  points will be added to the end. If this function returns false, the
+ *  object is left untouched.
  *
  * \param object          A pointer to an existing SEEKTABLE object.
  * \param new_num_points  The desired length of the array; may be \c 0.
@@ -1611,7 +1612,8 @@ FLAC_API FLAC__bool FLAC__metadata_object_vorbiscomment_set_vendor_string(FLAC__
 /** Resize the comment array.
  *
  *  If the size shrinks, elements will truncated; if it grows, new empty
- *  fields will be added to the end.
+ *  fields will be added to the end.  If this function returns false, the
+ *  object is left untouched.
  *
  * \param object            A pointer to an existing VORBIS_COMMENT object.
  * \param new_num_comments  The desired length of the array; may be \c 0.
@@ -1891,7 +1893,8 @@ FLAC_API void FLAC__metadata_object_cuesheet_track_delete(FLAC__StreamMetadata_C
 /** Resize a track's index point array.
  *
  *  If the size shrinks, elements will truncated; if it grows, new blank
- *  indices will be added to the end.
+ *  indices will be added to the end. If this function returns false, the
+ *  track object is left untouched.
  *
  * \param object           A pointer to an existing CUESHEET object.
  * \param track_num        The index of the track to modify.  NOTE: this is not
@@ -1977,7 +1980,8 @@ FLAC_API FLAC__bool FLAC__metadata_object_cuesheet_track_delete_index(FLAC__Stre
 /** Resize the track array.
  *
  *  If the size shrinks, elements will truncated; if it grows, new blank
- *  tracks will be added to the end.
+ *  tracks will be added to the end.  If this function returns false, the
+ *  object is left untouched.
  *
  * \param object            A pointer to an existing CUESHEET object.
  * \param new_num_tracks    The desired length of the array; may be \c 0.