Strings are UTF-8, and System.String is converted at a .NET call

🤖 Generated with [ECA](https://eca.dev)

Co-Authored-By: eca-agent <git@eca.dev>

_02_.Writing-programs.sz

@@ -902,6 +902,8 @@ Each entry in @code{import/extern} specifies a local Bjolang identifier, the ful
 max-int           ;; 2147483647
 }|
 
+.NET's own string, @code{System.String}, is UTF-16 and a different type from @code{string}. A .NET method that takes or returns one, or an array of them, is converted where it is called, so @code{trim} above takes and gives a Bjolang string; a @code{null} from .NET arrives as @code{""}. A .NET string inside another type, such as a @code{(Seq System.String)}, is not converted: @code{string->clr-string} and @code{clr-string->string} do it by hand.
+
 Avoid binding an external method to the name of an existing prelude function. Locally bound names and prelude symbols take precedence over @code{import/extern} declarations, which means an alias named @code{println} would simply be shadowed and ignored.
 
 @subsubsection{Classes: import/class}
@@ -920,6 +922,8 @@ The @code{import/class} form maps a .NET class to a Bjolang type, exposing its c
 (.ToUpper "shout")              ;; "SHOUT"
 }|
 
+A method that @code{string} does not have, like @code{ToUpper}, is called on the string converted to .NET's, so its indices and lengths are .NET's UTF-16 ones and not @code{string-length}'s bytes.
+
 As shown in the example above, you do not need to declare every method up front with @code{import/extern}. Once an object's type is known to the type checker, you can invoke any public method using @code{(.Method obj args ...)} and inspect properties using @code{(.-Property obj)}. Because @code{Append} returns the builder itself and Bjolang enforces explicit handling of return values, discard unused returns intentionally using @code{ignore}.
 
 @subsubsection{When .NET fails}