From f9f49ec75f0c29c05fb64b2d1aa059bc826817b3 Mon Sep 17 00:00:00 2001 From: crc Date: Thu, 21 Mar 2019 17:39:38 +0000 Subject: [PATCH] book: add some additional details on strings FossilOrigin-Name: aebd04b864161c8b0539ff56735584004e47c2a400a27ee02a553fb3fde3ef82 --- RETRO-Book.md | 54 +++++++++++++++++-- ...rogramming-Techniques-Working-With-Strings | 54 +++++++++++++++++-- 2 files changed, 102 insertions(+), 6 deletions(-) diff --git a/RETRO-Book.md b/RETRO-Book.md index ed82a5f..c2f1e0d 100644 --- a/RETRO-Book.md +++ b/RETRO-Book.md @@ -1687,9 +1687,27 @@ RETRO provides four words for searching within a string. ## Extraction -`s:left` -`s:right` -`s:substr` +To obtain a new string containing the first `n` characters from +a source string, use `s:left`: + +``` +'Hello_World #5 s:left +``` + +To obtain a new string containing the last `n` characters from +a source string, use `s:right`: + +``` +'Hello_World #5 s:right +``` + +If you need to extract data from the middle of the string, use +`s:substr`. This takes a string, the offset of the first +character, and the number of characters to extract. + +``` +'Hello_World #3 #5 s:substr +``` ## Joining @@ -1746,6 +1764,36 @@ which let you trim just the leading or trailing end as desired. `s:format` `s:empty` +## Controlling The Temporary Buffers + +As dicussed in the Lifetime subsection, temporary strings are +allocated in a rotating buffer. The details of this can be +altered by updating two variables. + +| Variable | Holds | +| ------------- | ---------------------------------------- | +| TempStrings | The number of temporary strings | +| TempStringMax | The maximum length of a temporary string | + +For example, to increase the number of temporary strings to +48: + +``` +#48 !TempStrings +``` + +The defaults are: + +| Variable | Default | +| ------------- | ------- | +| TempStrings | 32 | +| TempStringMax | 512 | + +It's also important to note that altering these will affect +the memory map for all temporary buffers. Do not use anything +already in the buffers after updating these or you will risk +data corruption and possible crashes. + # The Return Stack diff --git a/book/Programming-Techniques-Working-With-Strings b/book/Programming-Techniques-Working-With-Strings index 1562e9b..b06c7af 100644 --- a/book/Programming-Techniques-Working-With-Strings +++ b/book/Programming-Techniques-Working-With-Strings @@ -68,9 +68,27 @@ RETRO provides four words for searching within a string. ## Extraction -`s:left` -`s:right` -`s:substr` +To obtain a new string containing the first `n` characters from +a source string, use `s:left`: + +``` +'Hello_World #5 s:left +``` + +To obtain a new string containing the last `n` characters from +a source string, use `s:right`: + +``` +'Hello_World #5 s:right +``` + +If you need to extract data from the middle of the string, use +`s:substr`. This takes a string, the offset of the first +character, and the number of characters to extract. + +``` +'Hello_World #3 #5 s:substr +``` ## Joining @@ -126,3 +144,33 @@ which let you trim just the leading or trailing end as desired. `s:replace` `s:format` `s:empty` + +## Controlling The Temporary Buffers + +As dicussed in the Lifetime subsection, temporary strings are +allocated in a rotating buffer. The details of this can be +altered by updating two variables. + +| Variable | Holds | +| ------------- | ---------------------------------------- | +| TempStrings | The number of temporary strings | +| TempStringMax | The maximum length of a temporary string | + +For example, to increase the number of temporary strings to +48: + +``` +#48 !TempStrings +``` + +The defaults are: + +| Variable | Default | +| ------------- | ------- | +| TempStrings | 32 | +| TempStringMax | 512 | + +It's also important to note that altering these will affect +the memory map for all temporary buffers. Do not use anything +already in the buffers after updating these or you will risk +data corruption and possible crashes.