String - chung-leong/qb GitHub Wiki

QB is not designed for handling text. As such, there is no actual string type. While you may declare a variable to be "string," in reality it is just an array of integers.

The following code shows the true nature of strings in QB:

<?php

/**
  * @engine qb
  * @param string $s
  */
function test($s) {
  echo "$s " . count($s) . "\n";
}

test("Hello");

qb_compile();

test("Hello");

?>

Result:

Hello 1
Hello 5

When the test function runs as regular PHP, count($s) returns 1, because string in PHP is a scalar type. After the function has been compiled for QB, count($s) returns 5, as there are five bytes in "Hello".

QB never performs string-to-numeric conversion as the following example demonstrates:

<?php

/**
  * @engine qb
  * @param string $s
  */
function test($s) {
  $s += 5;
  echo "$s\n";
}

qb_compile();

test("10000");

?>

Result:

65555

The += operator in this case just adds 5 to each ASCII value in the array. In regular PHP, the result would be 10005.

The string type identifier (and its scalar counterpart char) only affects the behavior of echo:

<?php

/**
  * @engine qb
  * @param string $s
  * @param uint8[]$a
  */
function test($s, $a) {
  echo "$s $a\n";
}

qb_compile();

test("Hello", "Hello");

?>

Result:

Hello [72, 101, 108, 108, 111]

If a parameter is declared to be an array of uint16 and a string is given, the byte array will be interpreted as an uint16 array:

<?php

/**
  * @engine qb
  * @param uint8[]  $a1
  * @param uint16[] $a2
  */
function test($a1, $a2) {
  echo "$a1 $a2\n";
}

qb_compile();

test("Hello?", "Hello?");

?>

Result:

[72, 101, 108, 108, 111, 63] [25928, 27756, 16239]

A 16-bit integer takes up two bytes. A string with six bytes thus becomes an array with three uint16 elements. How the bytes are interpreted is platform dependent. x86 CPUs employ the little-endian scheme, where the first of the two bytes is the lower order byte. 'H' has the ASCII value 72 and 'e' has the value ASCII 101. The sequence "He" is therefore 72 + 101 * 256 = 25928.

Conversion to the other primitive types work in the same manner. It's also possible to provide a string to a parameter that was declared as a multi-dimensional array, as long as the length of the string is compatible. As for example, if a parameter is declared to be float64[][8], the length of the string must be a multiple of 8 * sizeof(float64) = 64.

Where possible, the QB VM will reuse the bytes inside the string directly instead of creating a copy. This means passing even very large arrays to a PHP+QB function can be done efficiently.

Beginning from version 2.3, QB is capable of automatically decoding UTF-8 strings passed as parameters. The string<base-type> syntax is used to indicate a Unicode string. If base-type is uint16, QB will decode a UTF-8 encoded string as an array of 16-bit integers. If base-type is uint32, it will decode it as 32-bit integers.

When a Unicode string is echo'ed, it'll be first encoded as UTF-8.