# mruby-encoding

This mrbgem provides a lightweight, "poorman's" encoding functionality for mruby. It is designed to offer basic encoding support, primarily focused on UTF-8 and ASCII-8BIT.

## Summary

- **License:** MIT
- **Author:** mruby developers
- **Supported Encodings:**
  - `Encoding::UTF_8`
  - `Encoding::ASCII_8BIT` (aliased as `Encoding::BINARY`)

## Functionality

This gem introduces an `Encoding` module and extends the `String` and `Integer` classes with encoding-related methods.

### `Encoding` Module

A module (not a class, unlike standard Ruby) that holds encoding constants.

- `Encoding::UTF_8`: Represents the UTF-8 encoding.
- `Encoding::ASCII_8BIT`: Represents the ASCII-8BIT encoding.
- `Encoding::BINARY`: An alias for `Encoding::ASCII_8BIT`.

### `String` Methods

- `string.valid_encoding? -> true or false`
  - Returns `true` if the string is correctly encoded (particularly useful for UTF-8 strings). For `ASCII-8BIT` strings, it generally returns `true`.
- `string.encoding -> EncodingConstant`
  - Returns the encoding of the string. This will be `Encoding::UTF_8` or `Encoding::BINARY`.
- `string.force_encoding(encoding_name) -> string`
  - Changes the string's reported encoding to the specified `encoding_name` (e.g., "UTF-8", "ASCII-8BIT", "BINARY").
  - The actual byte sequence of the string is not changed.
  - Raises an `ArgumentError` if an unsupported encoding name is provided.

### `Integer` Method

- `integer.chr(encoding_name = Encoding::BINARY) -> String`
  - Returns a single-character string represented by the integer.
  - If `encoding_name` is "UTF-8", the integer is treated as a Unicode codepoint.
  - If `encoding_name` is "ASCII-8BIT" or "BINARY" (the default), the integer is treated as a byte value (0-255).
  - Raises a `RangeError` if the integer is out of the valid range for the specified encoding.
  - Raises an `ArgumentError` for unknown encoding names.

## Usage Example

```ruby
# main.rb
if __ENCODING__ == "UTF-8"
  s = "helloあ"
  puts s.encoding  #=> Encoding::UTF_8
  puts s.valid_encoding? #=> true

  s2 = "\xff".force_encoding("UTF-8")
  puts s2.valid_encoding? #=> false

  s3 = "world"
  s3.force_encoding("BINARY")
  puts s3.encoding #=> Encoding::BINARY
  puts s3.valid_encoding? #=> true (ASCII-8BIT strings are generally considered valid)

  puts 65.chr #=> "A" (defaults to ASCII-8BIT)
  puts 230.chr("UTF-8") #=> "æ" (if U+00E6 is æ)
  # For mruby, this might be different based on actual UTF-8 char mapping
  # For example, 12354.chr("UTF-8") might be "あ"
else
  s = "hello"
  puts s.encoding #=> Encoding::BINARY (or ASCII-8BIT)

  # Attempting to force to UTF-8 in a non-UTF-8 mruby build might be limited
  # or behave as ASCII-8BIT depending on mruby's core string handling.
end

# Force encoding
my_string = "\xE3\x81\x82" # UTF-8 bytes for "あ"
puts my_string.encoding # Might be BINARY by default if not created as UTF-8 literal

my_string.force_encoding("UTF-8")
puts my_string.encoding #=> Encoding::UTF_8
puts my_string #=> あ

invalid_utf8 = "\xff\xfe"
invalid_utf8.force_encoding("UTF-8")
puts invalid_utf8.valid_encoding? #=> false

# Integer#chr
puts 65.chr # => "A"
puts 65.chr("BINARY") # => "A"

# When mruby is compiled with MRB_UTF8_STRING
if Object.const_defined?(:MRB_UTF8_STRING)
  puts 12354.chr("UTF-8") # => "あ"
  # puts 0x110000.chr("UTF-8") #=> RangeError
end

```