Updated Improving performance with Viper code (markdown)

Improving-performance-with-Viper-code.md

@@ -13,7 +13,7 @@ def add_to_array( a, n ):
         sum_array += a[i]
     return sum_array
 
-# The viper function, taking advantage of the viper data types
+# This decorator allows taking advantage of the viper data types:
 @micropython.viper
 # The function declaration uses type hints (type annotations
 # to cast parameters 
@@ -85,7 +85,7 @@ Please note that once assigned, the type of a viper variable cannot be changed (
     # The reverse order is also not allowed.
 ```
 
-Be aware: The viper code emitter analyzes of the code at compile time, determining the type of the variables. This is very unusual when coming from a Python background, where typing is dynamic and at runtime.
+Be aware: The viper code emitter analyzes of the code at compile time, determining the type of the variables. This is very unusual when coming from a Python background, where typing is dynamic and at runtime. On the other hand, most problems with viper variables are detected at compile time, before the program even runs, which is very nice!
 
 
 In case you are familiar with C: The viper data types are similar to some C language data types:
@@ -188,7 +188,7 @@ But this is a perhaps a little bit less readable.
 Viper ```int``` variables allow values from -2\*\*31 to 2\*\*31-1, whereas ```builtins.int``` variables have no practical range limit. For a `builtins.int`, if the value grows a lot, more memory will be allocated as needed.
 
 As a result, arithmetic operations on viper variables behave like operations in the C language 32 bit signed integer operations, for example:
-* Adding and subtracting wrap around if exceeding the range, for example `131072*32768=0`, since the result overflows 32 bits (just like C)
+* Arithmetic operations wrap around if exceeding the range, for example `131072*32768=0`, since the result overflows 32 bits (just like C)
 * Shift left (```x<<1```): the bits shifted beyond the 32 most significant bit get lost. 
 * No overflow exception
 
@@ -234,6 +234,12 @@ A viper ```int``` is not an object, and thus does not support methods such as ``
 
 The \*\* operator (exponentiation, `__pow__`) is not implemented for viper ```int```.
 
+
+Be aware: Do not shift left or right by a negative value, i.e. `x<<(-1)` or `x>>(-1)` should not be used because the result is undefined. This mirrors the C language definition for shift. Unlike regular MicroPython, there is no check for negative shift amounts.
+
+Be aware: If you are using a ESP32 or ESP32-S3 (or any XTENSAWIN processor, in MicroPython parlance), do not shift left by more than 31 bits. The result should be zero, but isn't. The RP2040 is not affected. Not tested yet for other processors. The workaround is to test if the shift amount is larger than 31 before shifting.
+
+
 ### int() casting
 
 Within viper decorated functions, the int() function will cast an expression to a viper `int`. Examples: