Update XZ Utils to 5.0.3 (in deps)

src/liblzma/api/lzma/filter.h

 /**
  * \file        lzma/filter.h
- * \brief       Common filter related types
+ * \brief       Common filter related types and functions
  */
 
 /*
  * Author: Lasse Collin
  *
  * This file has been put into the public domain.
  * You can do whatever you want with this file.
  *
  * See ../lzma.h for information about liblzma as a whole.
  */
@@ skipping 38 matching lines @@
          *              cannot be 64-bit.
          */
         lzma_vli id;
 
         /**
          * \brief       Pointer to filter-specific options structure
          *
          * If the filter doesn't need options, set this to NULL. If id is
          * set to LZMA_VLI_UNKNOWN, options is ignored, and thus
          * doesn't need be initialized.
-         *
-         * Some filters support changing the options in the middle of
-         * the encoding process. These filters store the pointer of the
-         * options structure and communicate with the application via
-         * modifications of the options structure.
          */
         void *options;
 
 } lzma_filter;
 
 
 /**
  * \brief       Test if the given Filter ID is supported for encoding
  *
  * Return true if the give Filter ID is supported for encoding by this
@@ skipping 42 matching lines @@
  *              - LZMA_MEM_ERROR
  *              - LZMA_OPTIONS_ERROR: Unsupported Filter ID and its options
  *                is not NULL.
  *              - LZMA_PROG_ERROR: src or dest is NULL.
  */
 extern LZMA_API(lzma_ret) lzma_filters_copy(const lzma_filter *src,
                 lzma_filter *dest, lzma_allocator *allocator) lzma_nothrow;
 
 
 /**
- * \brief       Calculate rough memory requirements for raw encoder
+ * \brief       Calculate approximate memory requirements for raw encoder
  *
- * Because the calculation is rough, this function can be used to calculate
- * the memory requirements for Block and Stream encoders too.
+ * This function can be used to calculate the memory requirements for
+ * Block and Stream encoders too because Block and Stream encoders don't
+ * need significantly more memory than raw encoder.
  *
  * \param       filters     Array of filters terminated with
  *                          .id == LZMA_VLI_UNKNOWN.
  *
- * \return      Rough number of bytes of memory required for the given
- *              filter chain when encoding.
+ * \return      Number of bytes of memory required for the given
+ *              filter chain when encoding. If an error occurs,
+ *              for example due to unsupported filter chain,
+ *              UINT64_MAX is returned.
  */
 extern LZMA_API(uint64_t) lzma_raw_encoder_memusage(const lzma_filter *filters)
                 lzma_nothrow lzma_attr_pure;
 
 
 /**
- * \brief       Calculate rough memory requirements for raw decoder
+ * \brief       Calculate approximate memory requirements for raw decoder
  *
- * Because the calculation is rough, this function can be used to calculate
- * the memory requirements for Block and Stream decoders too.
+ * This function can be used to calculate the memory requirements for
+ * Block and Stream decoders too because Block and Stream decoders don't
+ * need significantly more memory than raw decoder.
  *
  * \param       filters     Array of filters terminated with
  *                          .id == LZMA_VLI_UNKNOWN.
  *
- * \return      Rough number of bytes of memory required for the given
- *              filter chain when decoding.
+ * \return      Number of bytes of memory required for the given
+ *              filter chain when decoding. If an error occurs,
+ *              for example due to unsupported filter chain,
+ *              UINT64_MAX is returned.
  */
 extern LZMA_API(uint64_t) lzma_raw_decoder_memusage(const lzma_filter *filters)
                 lzma_nothrow lzma_attr_pure;
 
 
 /**
  * \brief       Initialize raw encoder
  *
  * This function may be useful when implementing custom file formats.
  *
@@ skipping 79 matching lines @@
  *
  * \return      - LZMA_OK: Encoding was successful.
  *              - LZMA_BUF_ERROR: Not enough output buffer space.
  *              - LZMA_OPTIONS_ERROR
  *              - LZMA_MEM_ERROR
  *              - LZMA_DATA_ERROR
  *              - LZMA_PROG_ERROR
  *
  * \note        There is no function to calculate how big output buffer
  *              would surely be big enough. (lzma_stream_buffer_bound()
- *              works only for lzma_stream_buffer_encode().)
+ *              works only for lzma_stream_buffer_encode(); raw encoder
+ *              won't necessarily meet that bound.)
  */
 extern LZMA_API(lzma_ret) lzma_raw_buffer_encode(
                 const lzma_filter *filters, lzma_allocator *allocator,
                 const uint8_t *in, size_t in_size, uint8_t *out,
                 size_t *out_pos, size_t out_size) lzma_nothrow;
 
 
 /**
  * \brief       Single-call raw decoder
  *
@@ skipping 51 matching lines @@
  *
  * \return      - LZMA_OK
  *              - LZMA_OPTIONS_ERROR
  *              - LZMA_PROG_ERROR
  *
  * \note        Even this function won't validate more options than actually
  *              necessary. Thus, it is possible that encoding the properties
  *              succeeds but using the same options to initialize the encoder
  *              will fail.
  *
- * \note        It is OK to skip calling this function if
- *              lzma_properties_size() indicated that the size
- *              of the Filter Properties field is zero.
+ * \note        If lzma_properties_size() indicated that the size
+ *              of the Filter Properties field is zero, calling
+ *              lzma_properties_encode() is not required, but it
+ *              won't do any harm either.
  */
 extern LZMA_API(lzma_ret) lzma_properties_encode(
                 const lzma_filter *filter, uint8_t *props) lzma_nothrow;
 
 
 /**
  * \brief       Decode the Filter Properties field
  *
  * \param       filter      filter->id must have been set to the correct
  *                          Filter ID. filter->options doesn't need to be
@@ skipping 18 matching lines @@
                 const uint8_t *props, size_t props_size) lzma_nothrow;
 
 
 /**
  * \brief       Calculate encoded size of a Filter Flags field
  *
  * Knowing the size of Filter Flags is useful to know when allocating
  * memory to hold the encoded Filter Flags.
  *
  * \param       size    Pointer to integer to hold the calculated size
- * \param       filters Filter ID and associated options whose encoded
+ * \param       filter  Filter ID and associated options whose encoded
  *                      size is to be calculated
  *
  * \return      - LZMA_OK: *size set successfully. Note that this doesn't
- *                guarantee that filters->options is valid, thus
+ *                guarantee that filter->options is valid, thus
  *                lzma_filter_flags_encode() may still fail.
  *              - LZMA_OPTIONS_ERROR: Unknown Filter ID or unsupported options.
  *              - LZMA_PROG_ERROR: Invalid options
  *
  * \note        If you need to calculate size of List of Filter Flags,
  *              you need to loop over every lzma_filter entry.
  */
 extern LZMA_API(lzma_ret) lzma_filter_flags_size(
-                uint32_t *size, const lzma_filter *filters)
+                uint32_t *size, const lzma_filter *filter)
                 lzma_nothrow lzma_attr_warn_unused_result;
 
 
 /**
  * \brief       Encode Filter Flags into given buffer
  *
  * In contrast to some functions, this doesn't allocate the needed buffer.
  * This is due to how this function is used internally by liblzma.
  *
- * \param       filters     Filter ID and options to be encoded
+ * \param       filter      Filter ID and options to be encoded
  * \param       out         Beginning of the output buffer
  * \param       out_pos     out[*out_pos] is the next write position. This
  *                          is updated by the encoder.
  * \param       out_size    out[out_size] is the first byte to not write.
  *
  * \return      - LZMA_OK: Encoding was successful.
  *              - LZMA_OPTIONS_ERROR: Invalid or unsupported options.
  *              - LZMA_PROG_ERROR: Invalid options or not enough output
  *                buffer space (you should have checked it with
  *                lzma_filter_flags_size()).
  */
-extern LZMA_API(lzma_ret) lzma_filter_flags_encode(const lzma_filter *filters,
+extern LZMA_API(lzma_ret) lzma_filter_flags_encode(const lzma_filter *filter,
                 uint8_t *out, size_t *out_pos, size_t out_size)
                 lzma_nothrow lzma_attr_warn_unused_result;
 
 
 /**
  * \brief       Decode Filter Flags from given buffer
  *
- * The decoded result is stored into *filters. filters->options is
- * initialized but the old value is NOT free()d.
+ * The decoded result is stored into *filter. The old value of
+ * filter->options is not free()d.
  *
  * \return      - LZMA_OK
  *              - LZMA_OPTIONS_ERROR
  *              - LZMA_MEM_ERROR
  *              - LZMA_PROG_ERROR
  */
 extern LZMA_API(lzma_ret) lzma_filter_flags_decode(
-                lzma_filter *filters, lzma_allocator *allocator,
+                lzma_filter *filter, lzma_allocator *allocator,
                 const uint8_t *in, size_t *in_pos, size_t in_size)
                 lzma_nothrow lzma_attr_warn_unused_result;