lib/core: remove duplicates and improve doc of `NativeString` related services

Signed-off-by: Alexis Laferrière <alexis.laf@xymus.net>

diff --git a/lib/core/text/abstract_text.nit b/lib/core/text/abstract_text.nit
index b38eb27..e0e8dda 100644 (file)
--- a/lib/core/text/abstract_text.nit
+++ b/lib/core/text/abstract_text.nit
@@ -2041,22 +2041,43 @@ do
 end
 
 redef class NativeString
-       # Returns `self` as a new String.
+       # Get a `String` from the data at `self` copied into Nit memory
+       #
+       # Require: `self` is a null-terminated string.
        fun to_s_with_copy: String is abstract
 
-       # Returns `self` as a String of `length`.
+       # Get a `String` from `length` bytes at `self`
+       #
+       # The result may point to the data at `self` or
+       # it may make a copy in Nit controlled memory.
+       # This method should only be used when `self` was allocated by the Nit GC,
+       # or when manually controlling the deallocation of `self`.
        fun to_s_with_length(length: Int): String is abstract
 
-       # Returns a new instance of `String` with self as `_items`
+       # Get a `String` from the raw `length` bytes at `self`
+       #
+       # The default value of `length` is the number of bytes before
+       # the first null character.
        #
-       # /!\: Does not clean the items for compliance with UTF-8,
-       # Use only if you know what you are doing
-       fun to_s_unsafe(len: nullable Int): String is abstract
+       # The created `String` points to the data at `self`.
+       # This method should be used when `self` was allocated by the Nit GC,
+       # or when manually controlling the deallocation of `self`.
+       #
+       # /!\: This service does not clean the items for compliance with UTF-8,
+       # use only when the data has already been verified as valid UTF-8.
+       fun to_s_unsafe(length: nullable Int): String is abstract
 
-       # Returns `self` as a String with `bytelen` and `length` set
+       # Get a `String` from the raw `bytelen` bytes at `self` with `unilen` Unicode characters
+       #
+       # The created `String` points to the data at `self`.
+       # This method should be used when `self` was allocated by the Nit GC,
+       # or when manually controlling the deallocation of `self`.
+       #
+       # /!\: This service does not clean the items for compliance with UTF-8,
+       # use only when the data has already been verified as valid UTF-8.
        #
-       # SEE: `abstract_text::Text` for more infos on the difference
-       # between `Text::bytelen` and `Text::length`
+       # SEE: `abstract_text::Text` for more info on the difference
+       # between `Text::bytelen` and `Text::length`.
        fun to_s_full(bytelen, unilen: Int): String is abstract
 end
 

diff --git a/lib/core/text/flat.nit b/lib/core/text/flat.nit
index 3647344..87520c4 100644 (file)
--- a/lib/core/text/flat.nit
+++ b/lib/core/text/flat.nit
@@ -1168,8 +1168,7 @@ redef class NativeString
                return to_s_with_length(cstring_length)
        end
 
-       # Returns `self` as a String of `length`.
-       redef fun to_s_with_length(length): FlatString
+       redef fun to_s_with_length(length)
        do
                assert length >= 0
                return clean_utf8(length)
@@ -1184,7 +1183,6 @@ redef class NativeString
                return new FlatString.with_infos(self, len, 0)
        end
 
-       # Returns `self` as a new String.
        redef fun to_s_with_copy do return to_s_with_copy_and_length(cstring_length)
 
        # Get a `String` from `length` bytes at `self` copied into Nit memory