Merge pull request boriel-basic#569 from boriel/docs

doc: start of string.bas library documentation

docs/index.md

@@ -1,4 +1,4 @@
-#General 
+#General
 * [About](about.md)
 <br />About the ZX BASIC SDK
 
@@ -31,9 +31,12 @@ Get the latest version of ZX BASIC from the [archive](archive.md).
 * [Data types](types.md)
 <br />Language data types: Instead of working always with Floating Point numbers (also available), there are also some integer types which are faster an take less memory.
 
- * [Reserved words](identifier.md)
+* [Reserved words](identifier.md)
 <br />Comprehensive list (alphabetically ordered) of identifiers you shouldn't use as a ''variable name''. E.g. `FOR`, `PRINT`. If you want usage instructions on a statement, also look here.
 
+* [Standard libraries](library/stdlib.md)
+<br />Standard libraries that comes bundled with the ZX Basic compiler.
+
 ## Tutorials
 * [Programming tutorials](tutorials.md)
 <br />A collection of third-party tutorials about development with ZX BASIC.

docs/library.md

@@ -5,6 +5,16 @@
 This is a list of additions to the language that have been produced. They extend the functionality of the compiler by
 effectively adding reserved words to the language. At their heart, they are all SUB or FUNCTION sets.
 
+For the standard library go to the [standard library](library/stdlib.md) page.
+
+
+---
+## Non-standard libraries
+
+These ones might not be bundled yet with ZX Basic (mostly due to lack of time). If so, you have
+to copy the listing shown in this wiki and create the .bas file yourself, as explained in the following
+section.
+
 ###How to Include a Library Function
 You can either copy and paste the `SUB` or `FUNCTION` into your code, or, perhaps more easily,
 save the text as the recommended name (e.g. fSqrt.bas) and use `#include "fSqrt.bas"` at the start of the program.
@@ -84,7 +94,7 @@ Keep status updates scrolling in and sliding up without affecting the game windo
 
 * [windowAttrScrollUP.bas](library/windowattrscrollup.md)
 <br /> Subroutine to character scroll the attributes of a window of screen - really a handy addendum utility
-for [windowScrollUP.bas](library/windowscrollup.md) 
+for [windowScrollUP.bas](library/windowscrollup.md)
 
 ####Text Handling Library
 

docs/library/stdlib.md

@@ -0,0 +1,9 @@
+## Standard libraries
+
+These are libraries that came bundled with ZX Basic Compiler.
+Some libraries might be available only for some architectures. If so,
+they will be signaled as such. If no notice is shown, they are available for
+all.
+
+* [string.bas](../library/string.bas.md)<br />
+  Library for string manipulation.

docs/library/string.bas.md

@@ -0,0 +1,16 @@
+# STRING.BAS
+
+Library for generic string manipulation in Boriel ZX BASIC.
+
+By default, the first character in a ZX BASIC string starts at position 0.
+This is not very common in many BASIC dialects (i.e. Sinclair BASIC) were strings
+start at position 1. This is done by efficiency. If you want your strings
+to start at position 1, compile with `--string-base=1`.
+
+
+### String slicing
+Functions to retrieve a substring from a string:
+
+* [left](../string/left)
+* [mid](../string/mid)
+* [right](../string/right)

docs/library/string/left.md

@@ -0,0 +1,43 @@
+# LEFT
+
+Library: `#include <string.bas>`
+
+Returns the first n chars of a string
+
+
+###Syntax
+`left(s$, N)`
+
+Returns a substring of s$ of at most `N` characters starting from the left side.
+
+ * If the string length is shorter than `N`, the entire string will be returned.
+
+`left(s$, N)` is equivalent to `s$(TO N - 1)`
+
+## Examples
+
+```basic
+#include <string.bas>
+
+PRINT left("HELLO WORLD", 5)
+```
+Will print `HELLO`.
+
+---
+
+```basic
+#include <string.bas>
+
+PRINT left("HELLO WORLD", 20)
+```
+This will print `HELLO WORLD`. Despite asking for 20 chars, the string contains
+just 11 chars, so we get the entire string (they won't be filled with spaces).
+
+
+### See also
+
+ * [mid](mid.md)
+ * [right](right.md)
+
+
+Back to parent page: [String library](../string.bas.md)

docs/library/string/mid.md

@@ -0,0 +1,60 @@
+# MID
+
+Library: `#include <string.bas>`
+
+Return a portion of a string.
+
+
+###Syntax
+`mid(s$, start, N)`
+
+Returns a substring of s$ of at most `N` characters starting at the given
+`start` position.
+
+ * If the string length is shorter than `start + N` position (the `end` position is
+beyond the end of the string), the substring starting from `start` position will
+be returned.
+
+ * If the start position is beyond the end of the string, an empty string
+will be returned.
+
+`mid(s$, start, N)` is equivalent to `s$(start TO start + N - 1)`
+
+## Examples
+
+```basic
+#include <string.bas>
+
+PRINT mid("HELLO WORLD", 0, 5)
+```
+Will print `HELLO`.
+
+---
+
+```basic
+#include <string.bas>
+
+PRINT mid("HELLO WORLD", 6, 8)
+```
+This will print just `WORLD`.
+It'll start at position 6-th (for a 0-based string this is 7-th char), and print
+up to 8 chars, but since there are only 5, it will get just `WORLD`.
+
+---
+
+```basic
+#include <string.bas>
+
+PRINT mid("HELLO WORLD", 12, 5)
+```
+This will print just an empty string: start position is beyond the end
+of the string.
+
+
+### See also
+
+ * [left](left.md)
+ * [right](right.md)
+
+
+Back to parent page: [String library](../string.bas.md)

docs/library/string/right.md

@@ -0,0 +1,43 @@
+# RIGHT
+
+Library: `#include <string.bas>`
+
+Returns the last n chars of a string
+
+
+###Syntax
+`right(s$, N)`
+
+Returns a substring of s$ of at most `N` characters starting from the right side.
+
+ * If the string length is shorter than `N`, the entire string will be returned.
+
+`right(s$, N)` is equivalent to `s$(len(s$) - N - 1 TO)`
+
+## Examples
+
+```basic
+#include <string.bas>
+
+PRINT right("HELLO WORLD", 5)
+```
+Will print `WORLD`.
+
+---
+
+```basic
+#include <string.bas>
+
+PRINT left("HELLO WORLD", 20)
+```
+This will print `HELLO WORLD`. Despite asking for 20 chars, the string contains
+just 11 chars, so we get the entire string (they won't be filled with spaces).
+
+
+### See also
+
+ * [left](left.md)
+ * [mid](mid.md)
+
+
+Back to parent page: [String library](../string.bas.md)