From a5502e58631bc3fa58f351c1c6ba4e6aa22e582d Mon Sep 17 00:00:00 2001
From: =?utf8?q?Alexis=20Laferri=C3=A8re?= <alexis.laf@xymus.net>
Date: Mon, 18 Apr 2016 15:01:32 -0400
Subject: [PATCH] lib/core: remove duplicates and improve doc of
 `NativeString` related services
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

Signed-off-by: Alexis Laferrière <alexis.laf@xymus.net>
---
 lib/core/text/abstract_text.nit |   39 ++++++++++++++++++++++++++++++---------
 lib/core/text/flat.nit          |    4 +---
 2 files changed, 31 insertions(+), 12 deletions(-)

diff --git a/lib/core/text/abstract_text.nit b/lib/core/text/abstract_text.nit
index b38eb27..e0e8dda 100644
--- 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
--- 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
-- 
1.7.9.5