Add comprehensive documentation for bytes_util package

src/internal/bytes_util/README.mbt.md

@@ -0,0 +1,34 @@
+# Bytes Utility Package
+
+This package provides utility functions for working with byte arrays in MoonBit async library.
+
+## Overview
+
+The `bytes_util` package contains helper functions to process and convert byte data, particularly for ASCII string representations. This is primarily used internally by the async library for debugging and logging purposes.
+
+## Functions
+
+### `ascii_to_string`
+
+Converts a `BytesView` containing ASCII bytes to a human-readable string representation.
+
+**Description:**
+This function processes each byte in the input and converts it to a string representation suitable for display or debugging. It handles various ASCII characters differently:
+
+- Newline characters (`'\n'`) are preserved as literal newlines in the output
+- Carriage returns (`'\r'`) are escaped and displayed as `"\\r"`
+- Tab characters (`'\t'`) are escaped and displayed as `"\\t"`
+- Printable ASCII characters (codes 32-126) are converted directly to their character representation
+- Non-printable bytes are escaped as hexadecimal values (e.g., `"\\x0a"`)
+
+**Parameters:**
+- `ascii`: A `BytesView` containing the ASCII bytes to convert
+
+**Returns:**
+A `String` with human-readable representation of the ASCII bytes
+
+## Usage Notes
+
+- This package is primarily intended for internal use within the async library
+- The `ascii_to_string` function is useful for debugging binary data that may contain both printable and non-printable characters
+- Non-ASCII bytes (values > 126) are displayed as hexadecimal escape sequences

src/internal/bytes_util/README.mbt.md.backup

@@ -0,0 +1,45 @@
+# Bytes Utility Package
+
+This package provides utility functions for working with byte arrays in MoonBit async library.
+
+## Overview
+
+The `bytes_util` package contains helper functions to process and convert byte data, particularly for ASCII string representations. This is primarily used internally by the async library for debugging and logging purposes.
+
+## Functions
+
+### `ascii_to_string`
+
+Converts a `BytesView` containing ASCII bytes to a human-readable string representation.
+
+```moonbit
+pub fn ascii_to_string(ascii : BytesView) -> String
+```
+
+**Description:**
+This function processes each byte in the input and converts it to a string representation suitable for display or debugging. It handles various ASCII characters differently:
+
+- Newline characters (`'\n'`) are preserved as literal newlines in the output
+- Carriage returns (`'\r'`) are escaped and displayed as `"\\r"`
+- Tab characters (`'\t'`) are escaped and displayed as `"\\t"`
+- Printable ASCII characters (codes 32-126) are converted directly to their character representation
+- Non-printable bytes are escaped as hexadecimal values (e.g., `"\\x0a"`)
+
+**Parameters:**
+- `ascii`: A `BytesView` containing the ASCII bytes to convert
+
+**Returns:**
+A `String` with human-readable representation of the ASCII bytes
+
+**Example:**
+```moonbit
+let test_data = "Hello\tWorld\n".to_bytes()
+let result = ascii_to_string(test_data.op_as_view())
+println(result) // Output includes escaped tab and literal newline
+```
+
+## Usage Notes
+
+- This package is primarily intended for internal use within the async library
+- The `ascii_to_string` function is useful for debugging binary data that may contain both printable and non-printable characters
+- Non-ASCII bytes (values > 126) are displayed as hexadecimal escape sequences

src/internal/bytes_util/util.mbt

@@ -12,7 +12,27 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-///|
+/// Converts a BytesView containing ASCII bytes to a human-readable string.
+/// 
+/// This function processes each byte in the input and converts it to a string representation:
+/// - Newline characters (`'\n'`) are preserved as literal newlines
+/// - Carriage returns (`'\r'`) are escaped as `"\\r"`
+/// - Tab characters (`'\t'`) are escaped as `"\\t"`  
+/// - Printable ASCII characters (32-126) are converted directly to their character representation
+/// - Non-printable bytes are escaped as hexadecimal values (e.g., `"\\x0a"`)
+/// 
+/// # Parameters
+/// - `ascii`: A BytesView containing the ASCII bytes to convert
+/// 
+/// # Returns
+/// A String with human-readable representation of the ASCII bytes
+/// 
+/// # Example
+/// ```moonbit
+/// let bytes = @encoding/utf8.encode("Hello\tWorld\n")
+/// let result = ascii_to_string(bytes.op_as_view())
+/// // result contains escaped tab and literal newline
+/// ```
 pub fn ascii_to_string(ascii : BytesView) -> String {
   let builder = StringBuilder::new()
   for byte in ascii {

src/internal/bytes_util/util.mbt.backup

@@ -0,0 +1,31 @@
+// Copyright 2025 International Digital Economy Academy
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+///|
+pub fn ascii_to_string(ascii : BytesView) -> String {
+  let builder = StringBuilder::new()
+  for byte in ascii {
+    match byte {
+      '\n' => builder.write_char('\n')
+      '\r' => builder.write_string("\\r")
+      '\t' => builder.write_string("\\t")
+      32..=126 => builder.write_char(byte.to_int().unsafe_to_char())
+      x =>
+        builder
+        ..write_string("\\x")
+        ..write_string(x.to_int().to_string(radix=16))
+    }
+  }
+  builder.to_string()
+}

src/internal/bytes_util/util_test.mbt

@@ -0,0 +1,41 @@
+// Copyright 2025 International Digital Economy Academy
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+///|
+test "ascii_to_string with printable ASCII" {
+  let data = @encoding/utf8.encode("Hello World")
+  let result = ascii_to_string(data.op_as_view())
+  assert_eq(result, "Hello World")
+}
+
+///|
+test "ascii_to_string with newline" {
+  let data = @encoding/utf8.encode("Hello\nWorld")
+  let result = ascii_to_string(data.op_as_view())
+  assert_eq(result, "Hello\nWorld")
+}
+
+///|
+test "ascii_to_string with tab" {
+  let data = @encoding/utf8.encode("Hello\tWorld")
+  let result = ascii_to_string(data.op_as_view())
+  assert_eq(result, "Hello\\tWorld")
+}
+
+///|
+test "ascii_to_string with carriage return" {
+  let data = @encoding/utf8.encode("Hello\rWorld")
+  let result = ascii_to_string(data.op_as_view())
+  assert_eq(result, "Hello\\rWorld")
+}