all: fix broken docunits
[nit.git] / lib / standard / string.nit
index 28ad7b5..62d5ddc 100644 (file)
@@ -30,7 +30,6 @@ intrude import collection::array
 # High-level abstraction for all text representations
 abstract class Text
        super Comparable
-       super StringCapable
 
        redef type OTHER: Text
 
@@ -515,6 +514,29 @@ abstract class Text
                return b.to_s
        end
 
+       # Escape to include in a Makefile
+       #
+       # Unfortunately, some characters are not escapable in Makefile.
+       # These characters are `;`, `|`, `\`, and the non-printable ones.
+       # They will be rendered as `"?{hex}"`.
+       fun escape_to_mk: String do
+               var b = new FlatBuffer
+               for i in [0..length[ do
+                       var c = chars[i]
+                       if c == '$' then
+                               b.append("$$")
+                       else if c == ':' or c == ' ' or c == '#' then
+                               b.add('\\')
+                               b.add(c)
+                       else if c.ascii < 32 or c == ';' or c == '|' or c == '\\' or c == '=' then
+                               b.append("?{c.ascii.to_base(16, false)}")
+                       else
+                               b.add(c)
+                       end
+               end
+               return b.to_s
+       end
+
        # Return a string where Nit escape sequences are transformed.
        #
        #     var s = "\\n"
@@ -735,8 +757,6 @@ abstract class FlatText
 
        redef var length: Int = 0
 
-       init do end
-
        redef fun output
        do
                var i = 0
@@ -756,7 +776,7 @@ private abstract class StringCharView
 
        type SELFTYPE: Text
 
-       private var target: SELFTYPE
+       var target: SELFTYPE
 
        redef fun is_empty do return target.is_empty
 
@@ -777,6 +797,11 @@ private abstract class BufferCharView
 
 end
 
+# A `String` holds and manipulates an arbitrary sequence of characters.
+#
+# String objects may be created using literals.
+#
+#     assert "Hello World!" isa String
 abstract class String
        super Text
 
@@ -797,6 +822,9 @@ abstract class String
        #     assert "abc" * 0 == ""
        fun *(i: Int): SELFTYPE is abstract
 
+       # Insert `s` at `pos`.
+       #
+       #     assert "helloworld".insert_at(" ", 5)     == "hello world"
        fun insert_at(s: String, pos: Int): SELFTYPE is abstract
 
        redef fun substrings: Iterator[String] is abstract
@@ -969,7 +997,7 @@ class FlatString
 
        redef fun reversed
        do
-               var native = calloc_string(self.length + 1)
+               var native = new NativeString(self.length + 1)
                var length = self.length
                var items = self.items
                var pos = 0
@@ -1007,7 +1035,7 @@ class FlatString
 
        redef fun to_upper
        do
-               var outstr = calloc_string(self.length + 1)
+               var outstr = new NativeString(self.length + 1)
                var out_index = 0
 
                var myitems = self.items
@@ -1027,7 +1055,7 @@ class FlatString
 
        redef fun to_lower
        do
-               var outstr = calloc_string(self.length + 1)
+               var outstr = new NativeString(self.length + 1)
                var out_index = 0
 
                var myitems = self.items
@@ -1072,7 +1100,7 @@ class FlatString
                if real_items != null then
                        return real_items.as(not null)
                else
-                       var newItems = calloc_string(length + 1)
+                       var newItems = new NativeString(length + 1)
                        self.items.copy_to(newItems, length, index_from, 0)
                        newItems[length] = '\0'
                        self.real_items = newItems
@@ -1150,7 +1178,7 @@ class FlatString
 
                var total_length = my_length + its_length
 
-               var target_string = calloc_string(my_length + its_length + 1)
+               var target_string = new NativeString(my_length + its_length + 1)
 
                self.items.copy_to(target_string, my_length, index_from, 0)
                if s isa FlatString then
@@ -1181,7 +1209,7 @@ class FlatString
 
                var my_items = self.items
 
-               var target_string = calloc_string((final_length) + 1)
+               var target_string = new NativeString(final_length + 1)
 
                target_string[final_length] = '\0'
 
@@ -1291,6 +1319,7 @@ private class FlatStringCharView
 
 end
 
+# A mutable sequence of characters.
 abstract class Buffer
        super Text
 
@@ -1376,7 +1405,7 @@ abstract class Buffer
        #
        # SEE: `Char::is_letter` for the definition of a letter.
        #
-       #    var b = new FlatBuffer.from("jAVAsCriPt")"
+       #    var b = new FlatBuffer.from("jAVAsCriPt")
        #    b.capitalize
        #    assert b == "Javascript"
        #    b = new FlatBuffer.from("i am root")
@@ -1479,7 +1508,7 @@ class FlatBuffer
                # The COW flag can be set at false here, since
                # it does a copy of the current `Buffer`
                written = false
-               var a = calloc_string(c+1)
+               var a = new NativeString(c+1)
                if length > 0 then items.copy_to(a, length, 0, 0)
                items = a
                capacity = c
@@ -1495,7 +1524,7 @@ class FlatBuffer
        redef fun to_cstring
        do
                if is_dirty then
-                       var new_native = calloc_string(length + 1)
+                       var new_native = new NativeString(length + 1)
                        new_native[length] = '\0'
                        if length > 0 then items.copy_to(new_native, length, 0, 0)
                        real_items = new_native
@@ -1507,11 +1536,12 @@ class FlatBuffer
        # Create a new empty string.
        init do end
 
+       # Create a new string copied from `s`.
        init from(s: Text)
        do
                capacity = s.length + 1
                length = s.length
-               items = calloc_string(capacity)
+               items = new NativeString(capacity)
                if s isa FlatString then
                        s.items.copy_to(items, length, s.index_from, 0)
                else if s isa FlatBuffer then
@@ -1531,7 +1561,7 @@ class FlatBuffer
        do
                assert cap >= 0
                # _items = new NativeString.calloc(cap)
-               items = calloc_string(cap+1)
+               items = new NativeString(cap+1)
                capacity = cap
                length = 0
        end
@@ -1588,7 +1618,7 @@ class FlatBuffer
        redef fun reverse
        do
                written = false
-               var ns = calloc_string(capacity)
+               var ns = new NativeString(capacity)
                var si = length - 1
                var ni = 0
                var it = items
@@ -1659,7 +1689,6 @@ end
 
 private class FlatBufferCharView
        super BufferCharView
-       super StringCapable
 
        redef type SELFTYPE: FlatBuffer
 
@@ -1692,7 +1721,6 @@ private class FlatBufferCharView
 
        redef fun append(s)
        do
-               var my_items = target.items
                var s_length = s.length
                if target.capacity < s.length then enlarge(s_length + target.length)
        end
@@ -2095,11 +2123,16 @@ end
 
 # Native strings are simple C char *
 extern class NativeString `{ char* `}
-       super StringCapable
        # Creates a new NativeString with a capacity of `length`
        new(length: Int) is intern
+
+       # Get char at `index`.
        fun [](index: Int): Char is intern
+
+       # Set char `item` at index.
        fun []=(index: Int, item: Char) is intern
+
+       # Copy `self` to `dest`.
        fun copy_to(dest: NativeString, length: Int, from: Int, to: Int) is intern
 
        # Position of the first nul character.
@@ -2109,7 +2142,11 @@ extern class NativeString `{ char* `}
                while self[l] != '\0' do l += 1
                return l
        end
+
+       # Parse `self` as an Int.
        fun atoi: Int is intern
+
+       # Parse `self` as a Float.
        fun atof: Float is extern "atof"
 
        redef fun to_s
@@ -2117,6 +2154,7 @@ extern class NativeString `{ char* `}
                return to_s_with_length(cstring_length)
        end
 
+       # Returns `self` as a String of `length`.
        fun to_s_with_length(length: Int): FlatString
        do
                assert length >= 0
@@ -2124,10 +2162,11 @@ extern class NativeString `{ char* `}
                return str
        end
 
+       # Returns `self` as a new String.
        fun to_s_with_copy: FlatString
        do
                var length = cstring_length
-               var new_self = calloc_string(length + 1)
+               var new_self = new NativeString(length + 1)
                copy_to(new_self, length, 0, 0)
                var str = new FlatString.with_infos(new_self, length, 0, length - 1)
                new_self[length] = '\0'
@@ -2136,11 +2175,6 @@ extern class NativeString `{ char* `}
        end
 end
 
-# StringCapable objects can create native strings
-interface StringCapable
-       protected fun calloc_string(size: Int): NativeString is intern
-end
-
 redef class Sys
        private var args_cache: nullable Sequence[String]