feat(encoding): add {encode, decode}_to functions

[tonyfettes]

No description provided.

[peter-jerry-ye-code-review]

‼️ This code review is generated by a bot. Please verify the content before trusting it.

💡 [Potential Missing Documentation for New Functions]

• Category: Maintainability
• Code Snippet:

  pub fn Decoder::decode_lossy_to(...)
  pub fn encode_to(...)

• Recommendation: Add documentation comments similar to other functions in the codebase. For example:

  ///|
  /// Decodes the given byte sequence using the specified decoder and writes the
  /// result directly to a StringBuilder, replacing invalid sequences with the 
  /// Unicode Replacement Character (`U+FFFD`). Similar to `decode_to!`, but 
  /// handles malformed sequences gracefully.
  pub fn Decoder::decode_lossy_to(...)

• Reasoning: Both functions decode_lossy_to and encode_to lack proper documentation comments. Adding documentation will improve code understandability and maintainability. Other functions in the codebase have detailed documentation with clear parameter descriptions and examples. Following the existing pattern will make the API more consistent.

💡 [Potential Inconsistency in Error Handling]

• Category: Correctness
• Code Snippet:

  // In decode_to!
  Refill(t) => if stream { return } else { raise TruncatedError(t) }
  
  // In decode_lossy_to
  Refill(_) => if stream { return } else { continue self.decode_() }

• Recommendation: Consider making error handling consistent between the two functions. Either both should raise an error or both should continue decoding.
• Reasoning: The decode_to! function raises a TruncatedError when not in stream mode, while decode_lossy_to continues decoding. This inconsistency in error handling could lead to confusion or unexpected behavior. For maintainability and consistency, it would be better to handle similar conditions in the same way across functions.

💡 [Potential Redundant Buffer Writing in UTF16/UTF16LE Case]

• Category: Performance
• Code Snippet:

  UTF16 | UTF16LE => buffer.write_string(src)

• Recommendation: Consider writing characters individually like other encoding cases, for consistency:

  UTF16 | UTF16LE => 
    for char in src {
      write_utf16le_char(buffer, char)
    }

• Reasoning: While write_string might be optimized for these cases, following the same pattern of writing characters individually (like UTF8 and UTF16BE cases do) would make the code more consistent and potentially allow for better optimization opportunities in the future. It might also make the code easier to understand and modify, as all encoding paths follow the same logic.