Strings, arrays, and the less known sp(lit)str(ing) function

Strings, arrays, and the less known sp(lit)str(ing) function

Introduction

Looking through the different Nextion user groups on social networks, the Nextion user forum and a few not so official but Nextion related forums can be surprising. Sometimes, Nextion newbies ask questions or have issues although the required function is well (in a condensed manner for the experienced developer, I admit) documented on the Nextion Instruction Set (NIS) page, accessible through the menu of this website. On top of that, there is for sure one of my more than 100 Sunday blog articles which deals not only with that function, but goes often even beyond the usual usage of it. Apparently, I should sometimes move away from always trying to push the limits and listen to the “back to the roots!” calls by my potential readers…

Thus, I’ll try to shed some light on a less known but very mighty element of the Nextion programming language, the spstr function. Introduced only in the Nextion Editor v.1.61.1 in 2020, it has the last place in the “Operational commands” section and might have been overseen by the one or the other. It allows to split a string into parts which are separated by a delimiter. Not like some of the elementary C string functions, but it allows to use an index i to extract the text between the i-th and the i+1-th occurrence of the delimiter. This allows to look at the input string like an array of text elements which are separated by the delimiter.

Syntax

The usage of the spstr function is spstr <source>,<destination>,<delimiter>,<index> where source is the text to split up, for example the .txt content of a Variable or a Text component. Destination is the Variable or Text component’s .txt attribute where the extracted element will be copied into. Delimiter is some static text, usually a single character, for example ” ” if our words are separated by spaces. The zero based Index there the function which word to extract.

An example tells more than 1000 words

The most common array of text elements is something which we use permanently in our written language: A phrase is nothing other than an array of words, separated by a space character as a delimiter. For example “The quick brown fox jumps over the lazy dog”. I love this phrase because it contains every letter of the English alphabet at least one time which made it suitable for testing typewriters and teletype machines in a past era.
Now, seen as an array, it could be written as
phrase[0] = “The”
phrase[1] = “quick”
phrase[2] = “brown”
phrase[3] = “fox”
phrase[4] = “jumps”
phrase[5] = “over”
phrase[6] = “the”
phrase[7] = “lazy”
phrase[8] = “dog”
an here we are.

Let’s launch the Nextion editor add a Variable component va0 to our page, set its .sta attribute to “String”, increase its .txt_maxlen attribute to 50 because the default of 10 is too short to hold our phrase and finally write our phrase “The quick brown fox jumps over the lazy dog” into the .txt attribute. Furthermore, let’s add a Text component t0 to the page, where the extracted content will be displayed. Start the simulator and write the following in the Instruction Input Area:
spstr va0.txt,t0.txt,” “,4 and hit the return key. t0.txt will now show the word with the index 4 which is “jumps”. Similary, entering spstr va0.txt,t0.txt,” “,7 will fill t0 with “lazy”. In opposite to C code, where trying to access array elements beyond its boundaries can lead to unpredictable results up to hard faults, spstr will fail gracefully and simply return an empty string. Try spstr va0.txt,t0.txt,” “,9 and you’ll see the Text box t0 empty.

A slider to scroll through the words of our phrase

No, add a slider h0 to the page. Set its .minval to 0 and its .maxval to 9. In the Touch Release Event code pane, write spstr va0.txt,t0.txt,” “,h0.val. Add another line below: h0.val=h0.val. This line will improve the esthetics of you GUI, locking the slider into one of its 10 different positions and not stay somewhere in-between. As a further improvement, we’ll not only update t0.txt at the end of a move when the slider is released, but already during the move. Instead of duplicating the above code into the Touch Move code pane, we’ll simply add there: click h0,0 to trigger the Touch Release Code already during the move. Again, launch the simulator, and this time, there is no need to issue commands manually, just move the slider slowly from its start to its end position and you’ll see the words of our phrase appear in the Text box one after the other. Isn’t that miraculous?

Now using another common delimiter

Another common delimiter is the semicolon “;”, often used in CSV and other data structures. We’ll use it for more demonstration purposes. Let’s add another variable va1 to our page in a similar way as va0 above, and fill its .txt attribute with “one; two;three;four;five;six;seven;eight;nine;ten”. Also add another Text box t1 to the page. Go to the slider’s Touch Release code pane and add the line spstr va1.txt,t1.txt”;”,h0.val and launch the simulator again. Now, when moving the slider, in addition to our phrase appearing word by word in t0, we’ll see the words “one”, “two”, “three” etc. appear in the new Text component t1.

Using spstr for a lookup table

The spstr function works (as its name indicates) with strings. That doesn’t hinder us from putting numbers as text. We know that the covx function allows us to convert text into numbers when needed. Thus, we can build up a numeric lookup table by adding a third Variable component va2, similar to va1 and va0 above and fill its .txt with the squares of the worded numbers in the previous variable: “1;4;9;16;25;36;49;64;81;100”. But before we add the code to handle this in the slider h0’s Touch Release code pane, we add another line t1.txt+=” squared” to indicate what will happen below. Then, we need to add a number component n0 to our page, and a fourth (and last) Variable component with .sta=”String” which will be named by default va3, but we’ll change its name into tmp to make things clear. Back in the slider’s Touch Release code pane, we add first a line to extract the corresponding number from va2 as text into tmp, and then a line to convert the text in tmp into the Number component n0: spstr va2.txt,tmp.txt,”;”,h0.val followed by covx tmp.txt,n0.val,0,0 and we are done.

tltt 😉

Too lazy to type all the code (these few lines) ? No problem. You may download the .hmi file here: text_arrays1.HMI

Load it into the Nextion Editor and play with it by launching the debugger/simulator. And afterwards and as always, feel free to re-use this code or your modified version in your own projects.

Happy Nextioning!