diff --git a/src/internal/bytes_util/README.mbt.md b/src/internal/bytes_util/README.mbt.md new file mode 100644 index 00000000..9bcf36a4 --- /dev/null +++ b/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 diff --git a/src/internal/bytes_util/README.mbt.md.backup b/src/internal/bytes_util/README.mbt.md.backup new file mode 100644 index 00000000..bbd679c6 --- /dev/null +++ b/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 diff --git a/src/internal/bytes_util/util.mbt b/src/internal/bytes_util/util.mbt index 16cd419f..a57f4a4e 100644 --- a/src/internal/bytes_util/util.mbt +++ b/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 { diff --git a/src/internal/bytes_util/util.mbt.backup b/src/internal/bytes_util/util.mbt.backup new file mode 100644 index 00000000..16cd419f --- /dev/null +++ b/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() +} diff --git a/src/internal/bytes_util/util_test.mbt b/src/internal/bytes_util/util_test.mbt new file mode 100644 index 00000000..799f9969 --- /dev/null +++ b/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") +}