string.rb in opal-0.3.2

- old
+ new

@@ -1,20 +1,68 @@
-# A {String} object holds a sequence of bytes, typically representing
-# characters.
+# -*- encoding: utf-8 -*-
+
+# String objects holds a sequence of bytes, typically representing
+# characters. Strings may be constructed by using methods like
+# {String.new} or literals, like the following:
 #
-# Implementation Details
-# ======================
+#     String.new("foo")     # => "foo"
+#     "bar"                 # => "bar"
 #
-# For performance, strings in Opal are build directly on top of native
-# javascript strings, so that they are infact the same object. This has the side
-# effect that all strings are immutable, that is, they cannot be changed. Most
-# of the string methods that end in '!' are therefore not implemented, but their
-# counterparts are: 'upase' exists, but 'upcase!' does not, for example.
+# Strings in Opal are immutable; which means that their contents cannot
+# be changed. This means that a lot of methods like `strip!` are not
+# present, and will yield a `NoMethodError`. Thier immutable
+# counterparts are still available, which typically just return a new
+# string.
+#
+# Implementation details
+# ----------------------
+#
+# Ruby strings are toll-free bridged to native javascript strings,
+# meaning that anywhere that a ruby string is required, a normal
+# javascript string may be passed. This dramatically improves the
+# performance of Opal due to a lower overhead in allocating strings as
+# well as the ability to used functions of the String prototype to
+# perform many of the core ruby methods.
+#
+# It is due to this limitation that strings are immutable. Javascript
+# strings are immutable too, which limits what can be done with them in
+# regards to Ruby methods.
+#
+# Ruby compatibility
+# ------------------
+#
+# As discussed, {String} instances are immutable so they do not
+# implement any of the self mutable methods found in the ruby core
+# library. Most of these methods have their relative immutable
+# implementations, or alternative methods to take their place.
+#
+# Custom subclasses of {String} can be used, and are constructed in the
+# {.new} method. To due opals internals, a regular string is constructed
+# using `new String(string_content)`, and its class and method table
+# simply pointed at the custom subclass. As these custom subclasses are
+# simply javascript strings as well, they are also limited to being
+# immutable. This is because they share the same internal structre as
+# regular {String} instances.
+#
+# String instances will never actually have their {.allocate} methods
+# called. Due to the way opal bridges strings to javascript, when a new
+# string is constructed, its value must be know. This is not possible in
+# `allocate` as the value is not passed. Therefore the creation of
+# strings (including subclasses) is done in {.new} where the string
+# value is passed as an argument.
+#
+# Finally, strings do not currently include the `Comparable` module, as
+# it is not yet implemented. The main methods used by {String} from this
+# module are implemented directly as String methods. When `Comparable`
+# is implemented, these methods will be moved back to the module.
 class String
 
   def self.new(str = "")
-    `return new String(str);`
+    `var result = new String(str);
+    result.$klass = self;
+    result.$m = self.$m_tbl;
+    return result;`
   end
 
   # Copy - returns a new string containing `count` copies of the receiver.
   #
   # @example
@@ -135,15 +183,15 @@
   # This can also be used to create symbols that cannot be created using the
   # :xxxx notation.
   #
   # @return [Symbol]
   def to_sym
-    `return $opal.Y(self);`
+    `return VM.Y(self);`
   end
 
   def intern
-    `return $opal.Y(self);`
+    `return VM.Y(self);`
   end
 
   # Returns a new string with the characters from `self` in reverse order.
   #
   # @example
@@ -210,11 +258,11 @@
   # Match - if obj is a Regexp, then uses it to match against self, returning
   # nil if there is no match, or the index of the match location otherwise. If
   # obj is not a regexp, then it calls =~ on it, using the receiver as an
   # argument
   #
-  # @TODO passing a non regexp is not currently supported
+  # **TODO** passing a non regexp is not currently supported
   #
   # @param [Regexp, Objec] obj
   # @return [Numeric, nil]
   def =~(obj)
     obj.match self
@@ -293,10 +341,10 @@
 
   # Returns the index of the first occurance of the given `substr` or pattern in
   # self. Returns `nil` if not found. If the second param is present then it
   # specifies the index of self to begin searching.
   #
-  # @TODO: regexp and offsets not yet implemented.
+  # **TODO** regexp and offsets not yet implemented.
   #
   # @example
   #
   #     'hello'.index 'e'         # => 1
   #     'hello'.index 'lo'        # => 3