doc: add comments about utf8 compatibility for quantiels sketches

Author: proost

kll/include/kll_sketch.hpp

@@ -46,6 +46,11 @@ namespace kll_constants {
  * and nearly optimal accuracy per retained item.
  * See <a href="https://arxiv.org/abs/1603.05346v2">Optimal Quantile Approximation in Streams</a>.
  *
+ * Sketch that may retain string values.
+ * For sketches containing strings, cross-language portability depends on
+ * using compatible string encodings. This class does not by itself enforce
+ * UTF-8 validity for all string inputs.
+ *
  * <p>This is a stochastic streaming sketch that enables near real-time analysis of the
  * approximate distribution of items from a very large stream in a single pass, requiring only
  * that the items are comparable.
@@ -56,7 +61,7 @@ namespace kll_constants {
  * <p>As of May 2020, this implementation produces serialized sketches which are binary-compatible
  * with the equivalent Java implementation only when template parameter T = float
  * (32-bit single precision values).
- * 
+ *
  * <p>Given an input stream of <i>N</i> items, the <i>natural rank</i> of any specific
  * item is defined as its index <i>(1 to N)</i> in inclusive mode
  * or <i>(0 to N-1)</i> in exclusive mode
@@ -225,13 +230,17 @@ class kll_sketch {
 
     /**
      * Updates this sketch with the given data item.
+     * If cross-language portability is required, callers should ensure that
+     * the input string uses a compatible encoding (valid UTF-8).
      * @param item from a stream of items
      */
     template<typename FwdT>
     void update(FwdT&& item);
 
     /**
      * Merges another sketch into this one.
+     * If sketches contain strings, callers are responsible for ensuring that
+     * both sketches were built using compatible string encodings.
      * @param other sketch to merge into this one
      */
     template<typename FwdSk>

quantiles/include/quantiles_sketch.hpp

@@ -47,6 +47,11 @@ namespace quantiles_constants {
  * The analysis is obtained using get_rank() and get_quantile() functions,
  * the Probability Mass Function from get_PMF() and the Cumulative Distribution Function from get_CDF().
  *
+ * Sketch that may retain string values.
+ * For sketches containing strings, cross-language portability depends on
+ * using compatible string encodings. This class does not by itself enforce
+ * UTF-8 validity for all string inputs.
+ *
  * <p>Consider a large stream of one million values such as packet sizes coming into a network node.
  * The natural rank of any specific size value is its index in the hypothetical sorted
  * array of values.
@@ -206,13 +211,17 @@ class quantiles_sketch {
 
   /**
    * Updates this sketch with the given data item.
+   * If cross-language portability is required, callers should ensure that
+   * the input string uses a compatible encoding (valid UTF-8).
    * @param item from a stream of items
    */
   template<typename FwdT>
   void update(FwdT&& item);
 
   /**
    * Merges another sketch into this one.
+   * If sketches contain strings, callers are responsible for ensuring that
+   * both sketches were built using compatible string encodings.
    * @param other sketch to merge into this one
    */
   template<typename FwdSk>

req/include/req_sketch.hpp

@@ -35,6 +35,11 @@ namespace datasketches {
  * "Relative Error Streaming Quantiles" by Graham Cormode, Zohar Karnin, Edo Liberty,
  * Justin Thaler, Pavel Veselý, and loosely derived from a Python prototype written by Pavel Veselý.
  *
+ * Sketch that may retain string values.
+ * For sketches containing strings, cross-language portability depends on
+ * using compatible string encodings. This class does not by itself enforce
+ * UTF-8 validity for all string inputs.
+ *
  * <p>Reference: https://arxiv.org/abs/2004.01668</p>
  *
  * <p>This implementation differs from the algorithm described in the paper in the following:</p>
@@ -179,13 +184,17 @@ class req_sketch {
 
   /**
    * Updates this sketch with the given data item.
+   * If cross-language portability is required, callers should ensure that
+   * the input string uses a compatible encoding (valid UTF-8).
    * @param item from a stream of items
    */
   template<typename FwdT>
   void update(FwdT&& item);
 
   /**
    * Merges another sketch into this one.
+   * If sketches contain strings, callers are responsible for ensuring that
+   * both sketches were built using compatible string encodings.
    * @param other sketch to merge into this one
    */
   template<typename FwdSk>