encode_m 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d40d8792ba3c7759d3c00820f6646ff1e0ca1dced7260359d1c0b19105d582bd
-  data.tar.gz: 885ed4aa86eda098308e22da56be642437a2ee89a7d74594cdfde9b3ef6abff4
+  metadata.gz: 97b4b00c071667466ef61b65805c3143abcbc42720f629b1a0ee30f9fef0d200
+  data.tar.gz: 07e37e38818a96b8ba30330422d6ec32f31c33694a3c36a3515433b91cc6994e
 SHA512:
-  metadata.gz: e2547603a7a54d6371d93fe2d0fd524111ca477570ee36365c37a12cb7a1ec765d8a085aa60850b07e978f9ae85ee53c982aa365bf5eb2a8ed3ec9ed90a339b9
-  data.tar.gz: 6131029ca37383c3fdae7c908413a523603e25ebbc6c6594f11b909ca958b4e8120e294821544f7e8e64dd28dd0f4407c19088740b0104d37fbcb946305b8a5d
+  metadata.gz: b8cfd69a708969bdc2e2f16940f9597d12a4fd1b83021c60eaa82e1101626ee0d036d96433c3e930399c152022371dce01c4880d831ae39552135fa5d1db4ae7
+  data.tar.gz: 10146bf5686a83fa4036586f2380c46c29d9edd7a7808488646c7994f1a8ff0305eef3ace164aa1e9296cc77f155162e9674ed9ac5fce7cbb06ad2d3c2002ef2

data/CHANGELOG.md

@@ -5,6 +5,43 @@ All notable changes to the EncodeM project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0] - 2025-01-03
+
+### 🎉 Major Features
+- **Complete M language subscript support!** Now includes strings and composite keys
+- String encoding with proper `0xFF` prefix and escape sequences
+- Composite keys for hierarchical data structures (e.g., `M("users", 42, "email")`)
+- Full compatibility with YottaDB/GT.M subscript encoding
+
+### Added
+- `EncodeM::String` class for string subscripts
+- `EncodeM::Composite` class for multi-component keys
+- Support for variadic arguments in `M()` function
+- Automatic type detection (numeric strings parse as numbers)
+- Comprehensive test suite for string and composite features
+- Support for nil values (converted to empty strings)
+
+### Changed
+- Float values are now truncated to integers (M language only supports integer encoding)
+- `M()` function can now accept multiple arguments for composite keys
+- Decoder enhanced to handle strings and composite keys
+- Division operations now perform integer division
+
+### Examples
+```ruby
+# Strings
+M("Hello")                   # String encoding
+M("")                        # Empty string
+
+# Composite keys
+M("users", 42, "email")      # Database-style keys
+M(2025, 1, 15)               # Date as composite
+M("cache", namespace, key)    # Cache keys
+
+# Mixed types
+M("user", 123, "posts", -1)  # All types work together
+```
+
 ## [2.0.0] - 2025-09-03
 
 ### Changed

data/README.md

@@ -3,15 +3,25 @@
 [![Gem Version](https://badge.fury.io/rb/encode_m.svg)](https://badge.fury.io/rb/encode_m)
 [![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-Bringing the power of M language (MUMPS) numeric encoding to Ruby. Based on YottaDB/GT.M's 40-year production-tested algorithm.
+**🎉 Version 3.0: Complete M language subscript encoding - numbers, strings, and composite keys!**
+
+Bringing the power of M language (MUMPS) subscript encoding to Ruby. Build hierarchical database keys like `M("users", 42, "email")` with perfect sort order. Based on YottaDB/GT.M's 40-year production-tested algorithm.
 
 ## Why You Should Use EncodeM
 
-If you're building anything that stores numbers in a database or key-value store, EncodeM is a game-changer. The magic is simple but powerful: when you encode numbers with EncodeM, the resulting byte strings maintain numeric sort order. This means your database can compare and sort numbers **without ever decoding them** - just pure byte comparison like strcmp(). Imagine your B-tree indexes comparing numbers 3x faster because they never deserialize, or range queries that just compare raw bytes. This is the secret sauce that's been powering Epic (used by 70% of US hospitals) and other M language systems for 40 years.
+**Version 3.0 brings complete M language subscript support!** Not just numbers anymore - now you can encode strings and build powerful composite keys for hierarchical data structures.
+
+If you're building anything that stores data in a database or key-value store, EncodeM is a game-changer. The magic is simple but powerful: when you encode values with EncodeM, the resulting byte strings maintain perfect sort order. This means your database can compare and sort **without ever decoding** - just pure byte comparison like strcmp().
 
-Beyond the sorting superpower, EncodeM is surprisingly memory efficient. Small numbers (1-99) take just 2 bytes compared to 8 for a Float, and common values stay compact at 2-6 bytes. You get 18 digits of precision - more than Float but without BigDecimal's overhead. The encoding handles positive, negative, and zero correctly, maintaining perfect sort order across the entire numeric range.
+### What's New in v3.0:
+- **String encoding**: Strings sort correctly after all numbers
+- **Composite keys**: Build hierarchical keys like `M("users", 42, "profile", "email")`
+- **Full M compatibility**: Generate YottaDB/GT.M compatible subscripts
+- **Mixed types**: Combine numbers, strings, and more in a single key
 
-The best part? It's production-tested technology. This isn't some experimental algorithm - it's literally the same encoding that's been processing medical records and financial transactions since the 1980s in YottaDB/GT.M systems. If you're building a system where you need sortable numeric keys (think time-series data, financial ledgers, or any ordered numeric index), EncodeM gives you the performance of byte-level operations with the correctness of proper numeric comparison. Drop it in, encode your numbers, and watch your database operations get faster.
+Imagine building a user database where `M("users", userId, "posts", postId)` creates perfectly sortable hierarchical keys. Or time-series data with `M(2025, 1, 15, sensorId, "temperature")`. The encoding ensures all components sort correctly - numbers before strings, maintaining hierarchical order.
+
+This is production-tested technology - literally the same encoding that's been processing medical records and financial transactions since the 1980s in YottaDB/GT.M systems. Epic (70% of US hospitals) and VistA use this exact algorithm for their global arrays. Drop it in, encode your data, and watch your database operations get faster.
 
 ## About the M Language Heritage
 
@@ -19,11 +29,13 @@ The M language (formerly MUMPS - Massachusetts General Hospital Utility Multi-Pr
 
 ## Key Features
 
-- **Sortable Byte Encoding**: Numbers encode to bytes that sort correctly without decoding
+- **Complete M Language Support**: Numbers, strings, and composite keys
+- **Sortable Byte Encoding**: All types encode to bytes that sort correctly without decoding
+- **Hierarchical Keys**: Build multi-component database keys with perfect sort order
 - **Production-Tested**: Algorithm proven in healthcare and finance for 40 years
-- **Optimized for Real Use**: Special handling for common number ranges
-- **Memory Efficient**: Compact representation, especially for small integers
-- **Database-Friendly**: Perfect for indexing and byte-wise comparisons
+- **YottaDB Compatible**: Generate valid YottaDB/GT.M subscripts
+- **Memory Efficient**: Compact representation for all data types
+- **Database-Friendly**: Perfect for B-tree indexes and key-value stores
 
 ## Installation
 
@@ -41,40 +53,84 @@ $ gem install encode_m
 
 ## Usage
 
+### Numbers (Classic M encoding)
 ```ruby
 require 'encode_m'
 
 # Create numbers using the M() convenience method
 a = M(42)
-b = M(3.14)
+b = M(3.14)      # Floats are truncated to integers
 c = M(-100)
 
 # Arithmetic works naturally
-sum = a + b        # => EncodeM(45.14)
-product = a * M(2) # => EncodeM(84)
+sum = a + b        # => M(45)
+product = a * M(2) # => M(84)
 
 # The magic: encoded bytes sort correctly!
 numbers = [M(5), M(-10), M(0), M(100), M(-5)]
 sorted = numbers.sort  # Correctly sorted: -10, -5, 0, 5, 100
 
 # Perfect for databases - compare without decoding
-encoded_a = a.to_encoded  # => "\xBD\x43"
+encoded_a = a.to_encoded  # => "\xBD\x2B"
 encoded_b = b.to_encoded  # => "\xBC\x04"
-encoded_a < encoded_b      # => false (42 > 3.14)
+encoded_a < encoded_b      # => false (42 > 3)
+```
+
+### Strings (New in v3.0!)
+```ruby
+# Encode strings - they sort after all numbers
+name = M("Alice")
+empty = M("")        # Empty string
+
+# M language ordering: all numbers < all strings
+M(999999) < M("0")   # => true
 
-# Decode back to numbers
-original = EncodeM.decode(encoded_a)  # => 42
+# String comparison maintains byte order
+M("apple") < M("banana")  # => true
+```
+
+### Composite Keys (New in v3.0!)
+```ruby
+# Build hierarchical database keys
+user_email = M("users", 42, "email")
+user_name = M("users", 42, "name")
+user_post = M("users", 42, "posts", 1)
+
+# Perfect for time-series data
+event = M(2025, 1, 15, 14, 30, "sensor_123", "temperature")
+
+# Keys sort hierarchically
+keys = [
+  M("users", 2, "email"),
+  M("users", 1, "name"),
+  M("users", 1, "email"),
+  M("users", 2, "name")
+].sort
+# Result order:
+# ["users", 1, "email"]
+# ["users", 1, "name"]
+# ["users", 2, "email"]
+# ["users", 2, "name"]
+
+# Access components
+user_email[0].value  # => "users"
+user_email[1].value  # => 42
+user_email.to_a      # => ["users", 42, "email"]
+
+# Decode composite keys
+encoded = user_email.to_encoded
+decoded = EncodeM.decode_composite(encoded)  # => ["users", 42, "email"]
 ```
 
 ## Format Specification
 
-EncodeM uses the M language numeric encoding that guarantees lexicographic byte ordering matches numeric ordering.
+EncodeM uses the complete M language subscript encoding that guarantees lexicographic byte ordering matches logical ordering for all data types.
 
 ### Encoding Structure
 
 ```
-0x00      KEY_DELIMITER (terminator)
-0x01      STR_SUB_ESCAPE (escape in strings)
+0x00      KEY_DELIMITER (separates components in composite keys)
+0x01      STR_SUB_ESCAPE (escape byte for strings)
 ------- NEGATIVE NUMBERS (decreasing magnitude) -------
 0x3B      -999,999,999 to -100,000,000 (9 digits)
 0x3C      -99,999,999 to -10,000,000 (8 digits)
@@ -97,28 +153,46 @@ EncodeM uses the M language numeric encoding that guarantees lexicographic byte
 0xC2      1,000,000 to 9,999,999 (7 digits)
 0xC3      10,000,000 to 99,999,999 (8 digits)
 0xC4      100,000,000 to 999,999,999 (9 digits)
-0xFF      STR_SUB_PREFIX (string marker)
+------- STRINGS -------
+0xFF      STR_SUB_PREFIX (all strings start with this)
 ```
 
+### Numeric Encoding
 - **First byte**: Determines sign and magnitude range
 - **Following bytes**: Encode digit pairs (00-99) using lookup tables
 - **Terminator**: Negative numbers end with `0xFF` to maintain sort order
 
+### String Encoding
+- **Prefix**: All strings start with `0xFF`
+- **Content**: UTF-8 bytes of the string
+- **Escaping**: Special bytes are escaped:
+  - `0x00` → `0x01 0xFF`
+  - `0x01` → `0x01 0xFE`
+
+### Composite Key Encoding
+- **Structure**: Components separated by `0x00` (KEY_DELIMITER)
+- **Ordering**: Maintains hierarchical sort order
+- **Example**: `M("users", 42)` → `[0xFF "users" 0x00 0xBD 0x2B]`
+
 ### Encoding Examples
 
-| Number | Hex Bytes | Explanation |
-|--------|-----------|-------------|
-| -1000 | `40 EE FE FF` | 4-digit negative, mantissa, terminator |
-| -100 | `41 FD FE FF` | 3-digit negative, mantissa, terminator |
-| -10 | `42 EE FF` | 2-digit negative, mantissa, terminator |
-| -1 | `43 FD FF` | 1-digit negative, mantissa, terminator |
+| Value | Hex Bytes | Description |
+|-------|-----------|-------------|
+| -1000 | `3F FD EF FF` | 4-digit negative |
+| -1 | `43 FB FF` | 1-digit negative |
 | 0 | `80` | Zero (single byte) |
-| 1 | `BC 02` | 1-digit positive, mantissa |
-| 10 | `BD 11` | 2-digit positive, mantissa |
-| 100 | `BE 02 01` | 3-digit positive, mantissa |
-| 1000 | `BF 11 01` | 4-digit positive, mantissa |
-
-The encoding ensures: `bytewise_compare(encode(x), encode(y)) == numeric_compare(x, y)`
+| 1 | `BC 02` | 1-digit positive |
+| 42 | `BD 2B` | 2-digit positive |
+| 1000 | `BF 0B 01` | 4-digit positive |
+| "Hello" | `FF 48 65 6C 6C 6F` | String with 0xFF prefix |
+| "" | `FF` | Empty string |
+| ["users", 42] | `FF 75 73 65 72 73 00 BD 2B` | Composite key |
+| [2025, 1, 15] | `BF 14 19 00 BC 02 00 BD 10` | Date as composite |
+
+The encoding ensures:
+- `bytewise_compare(encode(x), encode(y)) == logical_compare(x, y)`
+- All numbers sort before all strings
+- Composite keys maintain hierarchical order
 
 ## Ordering Guarantees
 
@@ -138,13 +212,15 @@ This enables direct byte comparison in databases without decoding.
 
 | Method | Description | Example |
 |--------|-------------|---------|
-| `M(value)` | Create EncodeM number (global) | `M(42)` |
-| `EncodeM.new(value)` | Create EncodeM number | `EncodeM.new(42)` |
-| `EncodeM.decode(bytes)` | Decode bytes to number | `EncodeM.decode("\x41\x43")` → `42` |
-| `#to_encoded` | Get encoded byte string | `M(42).to_encoded` → `"\x41\x43"` |
-| `#to_i` | Convert to Integer | `M(3.14).to_i` → `3` |
-| `#to_f` | Convert to Float | `M(42).to_f` → `42.0` |
-| `#to_s` | Convert to String | `M(42).to_s` → `"42"` |
+| `M(value)` | Create encoded value | `M(42)`, `M("hello")` |
+| `M(*values)` | Create composite key | `M("users", 42, "email")` |
+| `EncodeM.new(value)` | Create encoded value | `EncodeM.new(42)` |
+| `EncodeM.new(*values)` | Create composite key | `EncodeM.new("users", 42)` |
+| `EncodeM.decode(bytes)` | Decode bytes to value | `EncodeM.decode("\xBD\x2B")` → `42` |
+| `EncodeM.decode_composite(bytes)` | Decode composite key | Returns array of components |
+| `#to_encoded` | Get encoded byte string | `M(42).to_encoded` → `"\xBD\x2B"` |
+| `#value` | Get original value | `M(42).value` → `42` |
+| `#to_a` | Get composite components | `M("a", 1).to_a` → `["a", 1]` |
 
 ### Arithmetic Operations
 
@@ -167,21 +243,43 @@ This enables direct byte comparison in databases without decoding.
 | `>=` | Greater or equal | `M(10) >= M(5)` → `true` |
 | `<=>` | Spaceship operator | `M(5) <=> M(10)` → `-1` |
 
-### Predicates
+### Numeric Methods
 
 | Method | Description | Example |
 |--------|-------------|---------|
+| `#to_i` | Convert to Integer | `M(3.14).to_i` → `3` |
+| `#to_f` | Convert to Float | `M(42).to_f` → `42.0` |
+| `#to_s` | Convert to String | `M(42).to_s` → `"42"` |
 | `#zero?` | Check if zero | `M(0).zero?` → `true` |
 | `#positive?` | Check if positive | `M(42).positive?` → `true` |
 | `#negative?` | Check if negative | `M(-5).negative?` → `true` |
 
+### String Methods
+
+| Method | Description | Example |
+|--------|-------------|---------|
+| `#to_s` | Get string value | `M("hello").to_s` → `"hello"` |
+| `#length` | String length | `M("hello").length` → `5` |
+| `#empty?` | Check if empty | `M("").empty?` → `true` |
+
+### Composite Methods
+
+| Method | Description | Example |
+|--------|-------------|---------|
+| `#[]` | Access component | `M("a", 1)[0]` → `M("a")` |
+| `#length` | Number of components | `M("a", 1, "b").length` → `3` |
+| `#to_a` | Get all components | `M("a", 1).to_a` → `["a", 1]` |
+
 ## Edge Cases & Limits
 
 ### Supported Values
 - **Integers**: Full range up to 18 digits
-- **Decimals**: Currently converts to integer (decimal support planned)
-- **Zero**: Handled as special case (single byte: `0x40`)
+- **Floats**: Truncated to integers (M language design)
+- **Strings**: Any UTF-8 string, with automatic escaping
+- **Composite Keys**: Unlimited components of mixed types
+- **Zero**: Handled as special case (single byte: `0x80`)
 - **Negative numbers**: Full support with proper ordering
+- **Nil**: Converted to empty string `""`
 
 ### Not Supported
 - **NaN**: Raises `ArgumentError`

data/encode_m.gemspec

@@ -5,46 +5,57 @@ Gem::Specification.new do |spec|
   spec.version       = EncodeM::VERSION
   spec.authors       = ['Steve Shreeve']
   spec.email         = ['steve.shreeve@gmail.com']
-  
-  spec.summary       = 'M language numeric encoding for Ruby - sortable, efficient, production-tested'
-  spec.description   = 'EncodeM brings a 40-year production-tested numeric encoding algorithm ' \
-                       'from YottaDB/GT.M to Ruby. This algorithm from the M language (MUMPS) ' \
-                       'provides efficient numeric handling with the unique property that ' \
-                       'encoded byte strings maintain sort order. Perfect for database ' \
-                       'operations, financial calculations, and systems requiring efficient ' \
-                       'sortable number storage. A practical alternative between Float and ' \
-                       'BigDecimal.'
+
+  spec.summary       = 'Complete M language subscript encoding - numbers, strings, and composite keys'
+  spec.description   = 'EncodeM v3.0 brings complete M language (MUMPS) subscript encoding to Ruby, ' \
+                       'supporting numbers, strings, and composite keys with perfect sort order. ' \
+                       'Build hierarchical database keys like M("users", 42, "email") that sort ' \
+                       'correctly as raw bytes. This 40-year production-tested algorithm from ' \
+                       'YottaDB/GT.M powers Epic (70% of US hospitals) and VistA. Perfect for ' \
+                       'B-tree indexes, key-value stores, and any system requiring sortable ' \
+                       'hierarchical keys. All types maintain correct ordering when compared ' \
+                       'as byte strings - no decoding needed.'
   spec.homepage      = 'https://github.com/shreeve/encode_m'
   spec.license       = 'MIT'
   spec.required_ruby_version = '>= 2.5.0'
-  
+
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = spec.homepage
   spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
   spec.metadata['bug_tracker_uri'] = "#{spec.homepage}/issues"
   spec.metadata['documentation_uri'] = "https://rubydoc.info/gems/encode_m"
-  
+
   spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z`.split("\x0").reject { |f| 
+    `git ls-files -z`.split("\x0").reject { |f|
       f.match(%r{^(test|spec|features)/}) ||
       f.match(%r{^\.}) ||
       f == 'Gemfile.lock'
     }
   end
   spec.require_paths = ['lib']
-  
+
   spec.add_development_dependency 'bundler', '~> 2.0'
   spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'minitest', '~> 5.0'
   spec.add_development_dependency 'minitest-reporters', '~> 1.6'
   spec.add_development_dependency 'benchmark-ips', '~> 2.10'
-  
+
   spec.post_install_message = <<-MSG
-Thank you for installing EncodeM!
+Thank you for installing EncodeM v3.0!
+
+🎉 NEW: Complete M language support - numbers, strings, and composite keys!
 
 Quick start:
   require 'encode_m'
-  a = M(42)  # Create a number with M language encoding
+
+  # Numbers
+  M(42)
+
+  # Strings
+  M("Hello")
+
+  # Composite keys
+  M("users", 42, "email")
 
 Learn more: https://github.com/shreeve/encode_m
 MSG

data/lib/encode_m/composite.rb

@@ -0,0 +1,105 @@
+# Composite key encoding for M language subscripts
+module EncodeM
+  class Composite
+    include Comparable
+    
+    attr_reader :components, :encoded
+    
+    def initialize(*components)
+      raise ArgumentError, "Composite key requires at least one component" if components.empty?
+      
+      @components = components.map { |c| normalize_component(c) }
+      @encoded = encode_composite(@components)
+    end
+    
+    def to_a
+      @components.map do |component|
+        case component
+        when EncodeM::Numeric
+          component.value
+        when EncodeM::String
+          component.value
+        else
+          component
+        end
+      end
+    end
+    
+    def to_encoded
+      @encoded
+    end
+    
+    def inspect
+      "EncodeM::Composite(#{to_a.map(&:inspect).join(', ')})"
+    end
+    
+    def [](index)
+      @components[index]
+    end
+    
+    def length
+      @components.length
+    end
+    
+    alias size length
+    
+    # Comparison operations
+    def <=>(other)
+      case other
+      when EncodeM::Composite
+        @encoded <=> other.encoded
+      when EncodeM::Numeric, EncodeM::String
+        # Single values sort before composites with same first element
+        # This maintains hierarchical ordering
+        first_comparison = @components.first <=> other
+        first_comparison == 0 ? 1 : first_comparison
+      else
+        nil
+      end
+    end
+    
+    def ==(other)
+      case other
+      when EncodeM::Composite
+        @components == other.components
+      when Array
+        to_a == other
+      else
+        false
+      end
+    end
+    
+    alias eql? ==
+    
+    def hash
+      @components.hash
+    end
+    
+    private
+    
+    def normalize_component(value)
+      case value
+      when EncodeM::Numeric, EncodeM::String
+        value
+      when EncodeM::Composite
+        raise ArgumentError, "Cannot nest composite keys"
+      when ::Numeric  # Use :: to ensure we get Ruby's Numeric
+        EncodeM::Numeric.new(value)
+      when ::String
+        EncodeM::String.new(value)
+      when NilClass
+        EncodeM::String.new("")  # nil becomes empty string in M
+      else
+        raise ArgumentError, "Unsupported type in composite key: #{value.class}"
+      end
+    end
+    
+    def encode_composite(components)
+      encoded_parts = components.map(&:to_encoded)
+      
+      # Join with KEY_DELIMITER (0x00)
+      # Each component is separated by 0x00 to maintain hierarchical sorting
+      encoded_parts.join([Encoder::KEY_DELIMITER].pack('C'))
+    end
+  end
+end

data/lib/encode_m/decoder.rb

@@ -1,4 +1,4 @@
-# Decoder for M language numeric encoding
+# Decoder for M language encoding (numeric and string)
 module EncodeM
   class Decoder
     POS_DECODE = Encoder::POS_CODE.each_with_index.map { |v, i| [v, i] }.to_h.freeze
@@ -6,14 +6,49 @@ module EncodeM
 
     def self.decode(encoded_bytes)
       bytes = encoded_bytes.unpack('C*')
-      return 0 if bytes[0] == Encoder::SUBSCRIPT_ZERO
-
+      
+      # Check for string prefix
+      if bytes[0] == Encoder::STR_SUB_PREFIX
+        decode_string(bytes)
+      elsif bytes[0] == Encoder::SUBSCRIPT_ZERO
+        0
+      else
+        decode_numeric(bytes)
+      end
+    end
+    
+    def self.decode_composite(encoded_bytes)
+      components = []
+      bytes = encoded_bytes.unpack('C*')
+      current = []
+      
+      bytes.each do |byte|
+        if byte == Encoder::KEY_DELIMITER
+          # End of component
+          unless current.empty?
+            components << decode(current.pack('C*'))
+            current = []
+          end
+        else
+          current << byte
+        end
+      end
+      
+      # Don't forget the last component
+      components << decode(current.pack('C*')) unless current.empty?
+      
+      components
+    end
+    
+    private
+    
+    def self.decode_numeric(bytes)
       first_byte = bytes[0]
-
+      
       # Determine if negative based on first byte
       # Negative: 0x3B-0x43, Positive: 0xBC-0xC4
       is_negative = first_byte < Encoder::SUBSCRIPT_ZERO
-
+      
       if is_negative
         decode_table = NEG_DECODE
       else
@@ -37,5 +72,24 @@ module EncodeM
 
       is_negative ? -result : result
     end
+    
+    def self.decode_string(bytes)
+      result = []
+      i = 1  # Skip the 0xFF prefix
+      
+      while i < bytes.length
+        if bytes[i] == Encoder::STR_SUB_ESCAPE && i + 1 < bytes.length
+          # Unescape: next byte is XORed with 0xFF
+          result << (bytes[i + 1] ^ 0xFF)
+          i += 2
+        else
+          result << bytes[i]
+          i += 1
+        end
+      end
+      
+      # Force UTF-8 encoding for proper string handling
+      result.pack('C*').force_encoding('UTF-8')
+    end
   end
 end

data/lib/encode_m/numeric.rb

@@ -59,12 +59,30 @@ module EncodeM
 
     # M language feature: encoded comparison
     def <=>(other)
-      @encoded <=> self.class.new(other).encoded
+      case other
+      when EncodeM::Numeric
+        @encoded <=> other.encoded
+      when EncodeM::String
+        -1  # Numbers always sort before strings in M language
+      when EncodeM::Composite
+        # Let Composite handle the comparison
+        -(other <=> self)
+      when Numeric
+        @encoded <=> self.class.new(other).encoded
+      else
+        nil
+      end
     end
 
     def ==(other)
-      return false unless other.is_a?(self.class) || other.is_a?(::Numeric)
-      @value == coerce_value(other)
+      case other
+      when EncodeM::Numeric
+        @value == other.value
+      when Numeric
+        @value == other
+      else
+        false
+      end
     end
 
     def abs
@@ -91,11 +109,6 @@ module EncodeM
       end
     end
 
-    # Direct encoded comparison - key M language feature
-    def encoded_compare(other)
-      @encoded <=> other.encoded
-    end
-
     private
 
     def parse_value(val)
@@ -105,10 +118,10 @@ module EncodeM
       when Float
         raise ArgumentError, "Cannot represent Infinity" if val.infinite?
         raise ArgumentError, "Cannot represent NaN" if val.nan?
-        val
-      when String
+        val.to_i  # M language only supports integer encoding
+      when ::String
         if val.include?('.')
-          Float(val)
+          Float(val).to_i  # M language only supports integer encoding
         else
           Integer(val)
         end

data/lib/encode_m/string.rb

@@ -0,0 +1,85 @@
+# String encoding for M language subscripts
+module EncodeM
+  class String
+    include Comparable
+
+    attr_reader :value, :encoded
+
+    def initialize(value)
+      @value = value.to_s
+      @encoded = encode_string(@value)
+    end
+
+    def to_s
+      @value
+    end
+
+    def to_encoded
+      @encoded
+    end
+
+    def inspect
+      "EncodeM::String(#{@value.inspect})"
+    end
+
+    # String-specific predicates
+    def empty?
+      @value.empty?
+    end
+
+    def length
+      @value.length
+    end
+
+    # Comparison operations
+    def <=>(other)
+      case other
+      when EncodeM::String
+        @encoded <=> other.encoded
+      when EncodeM::Numeric
+        1  # Strings always sort after numbers in M language
+      when EncodeM::Composite
+        # Let Composite handle the comparison
+        -(other <=> self)
+      else
+        nil
+      end
+    end
+
+    def ==(other)
+      case other
+      when EncodeM::String
+        @value == other.value
+      when ::String
+        @value == other
+      else
+        false
+      end
+    end
+
+    alias eql? ==
+
+    def hash
+      @value.hash
+    end
+
+    private
+
+    def encode_string(str)
+      result = [Encoder::STR_SUB_PREFIX]  # 0xFF prefix for strings
+
+      str.bytes.each do |byte|
+        if byte == Encoder::KEY_DELIMITER || byte == Encoder::STR_SUB_ESCAPE
+          # Escape special bytes: 0x00 and 0x01
+          # Use 0x01 followed by (byte XOR 0xFF)
+          result << Encoder::STR_SUB_ESCAPE
+          result << (byte ^ 0xFF)
+        else
+          result << byte
+        end
+      end
+
+      result.pack('C*')
+    end
+  end
+end

data/lib/encode_m/version.rb

@@ -1,4 +1,4 @@
 module EncodeM
-  VERSION = "2.0.0"
-  # Honoring 40 years of M language (MUMPS) innovation from GT.M/YottaDB
+  VERSION = "3.0.0"
+  # Complete M language subscript encoding - now with strings and composite keys!
 end

data/lib/encode_m.rb

@@ -1,31 +1,69 @@
-# EncodeM - Bringing M language numeric encoding to Ruby
+# EncodeM - Complete M language subscript encoding for Ruby
 # Based on YottaDB/GT.M's 40-year production-tested algorithm
 
 require 'encode_m/version'
 require 'encode_m/encoder'
 require 'encode_m/decoder'
 require 'encode_m/numeric'
+require 'encode_m/string'
+require 'encode_m/composite'
 
 module EncodeM
   class Error < StandardError; end
 
-  # Factory method honoring M language convention
-  def self.new(value)
-    Numeric.new(value)
+  # Factory method supporting all M types
+  def self.new(*values)
+    if values.length == 1
+      create_single(values[0])
+    else
+      Composite.new(*values)
+    end
   end
 
   # Decode - reverse the M encoding
   def self.decode(encoded)
     Decoder.decode(encoded)
   end
+  
+  # Decode composite keys
+  def self.decode_composite(encoded)
+    Decoder.decode_composite(encoded)
+  end
 
-  # Alias for M language users
-  def self.M(value)
-    Numeric.new(value)
+  # M language style constructor
+  def self.M(*values)
+    if values.length == 1
+      create_single(values[0])
+    else
+      Composite.new(*values)
+    end
+  end
+  
+  private
+  
+  def self.create_single(value)
+    case value
+    when EncodeM::Numeric, EncodeM::String, EncodeM::Composite
+      value  # Already encoded
+    when ::Numeric  # Use :: to ensure we get Ruby's Numeric, not EncodeM::Numeric
+      Numeric.new(value)
+    when ::String
+      # Try to parse as a number first
+      begin
+        Numeric.new(value)
+      rescue ArgumentError
+        # Not a number, treat as string
+        String.new(value)
+      end
+    when NilClass
+      String.new("")  # nil becomes empty string in M
+    else
+      raise ArgumentError, "Unsupported type: #{value.class}"
+    end
   end
 end
 
 # Global convenience method (like M language global functions)
-def M(value)
-  EncodeM::Numeric.new(value)
+def M(*values)
+  EncodeM.M(*values)
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: encode_m
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Steve Shreeve
@@ -79,11 +79,13 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.10'
-description: EncodeM brings a 40-year production-tested numeric encoding algorithm
-  from YottaDB/GT.M to Ruby. This algorithm from the M language (MUMPS) provides efficient
-  numeric handling with the unique property that encoded byte strings maintain sort
-  order. Perfect for database operations, financial calculations, and systems requiring
-  efficient sortable number storage. A practical alternative between Float and BigDecimal.
+description: EncodeM v3.0 brings complete M language (MUMPS) subscript encoding to
+  Ruby, supporting numbers, strings, and composite keys with perfect sort order. Build
+  hierarchical database keys like M("users", 42, "email") that sort correctly as raw
+  bytes. This 40-year production-tested algorithm from YottaDB/GT.M powers Epic (70%
+  of US hospitals) and VistA. Perfect for B-tree indexes, key-value stores, and any
+  system requiring sortable hierarchical keys. All types maintain correct ordering
+  when compared as byte strings - no decoding needed.
 email:
 - steve.shreeve@gmail.com
 executables: []
@@ -97,10 +99,13 @@ files:
 - Rakefile
 - encode_m.gemspec
 - lib/encode_m.rb
+- lib/encode_m/composite.rb
 - lib/encode_m/decoder.rb
 - lib/encode_m/encoder.rb
 - lib/encode_m/numeric.rb
+- lib/encode_m/string.rb
 - lib/encode_m/version.rb
+- logo.png
 homepage: https://github.com/shreeve/encode_m
 licenses:
 - MIT
@@ -110,14 +115,10 @@ metadata:
   changelog_uri: https://github.com/shreeve/encode_m/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/shreeve/encode_m/issues
   documentation_uri: https://rubydoc.info/gems/encode_m
-post_install_message: |
-  Thank you for installing EncodeM!
-
-  Quick start:
-    require 'encode_m'
-    a = M(42)  # Create a number with M language encoding
-
-  Learn more: https://github.com/shreeve/encode_m
+post_install_message: "Thank you for installing EncodeM v3.0!\n\n\U0001F389 NEW: Complete
+  M language support - numbers, strings, and composite keys!\n\nQuick start:\n  require
+  'encode_m'\n\n  # Numbers\n  M(42)\n\n  # Strings\n  M(\"Hello\")\n\n  # Composite
+  keys\n  M(\"users\", 42, \"email\")\n\nLearn more: https://github.com/shreeve/encode_m\n"
 rdoc_options: []
 require_paths:
 - lib
@@ -134,5 +135,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.7.1
 specification_version: 4
-summary: M language numeric encoding for Ruby - sortable, efficient, production-tested
+summary: Complete M language subscript encoding - numbers, strings, and composite
+  keys
 test_files: []