SQLite Forum

doc: prepare.html: nByte performance advantage?

doc: prepare.html: nByte performance advantage?

(1) By Matthew Mario Di Pasquale (ma11hew28) on 2020-04-13 23:02:56 [link]

["Compiling An SQL Statement" in the SQLite Documentation][1] says:

> If the caller knows that the supplied string is nul-terminated, then there is a small performance advantage to passing an nByte parameter that is the number of bytes in the input string including the nul-terminator.

Is that true?

I looked at the source code of the sqlite3Prepare() routine in src/prepare.c, and the execution path seems like it'd be the same whether nBytes is -1 or the number of bytes in zSql plus one.

    if( nBytes>=0 && (nBytes==0 || zSql[nBytes-1]!=0) ){
      /* . . . */
      /* Wouldn't either value for nBytes take this path? */

Perhaps I'm missing something.

Anyway: I just noticed that nByte in the documentation should be renamed to nBytes (to match the source code).

  [1]: https://www.sqlite.org/c3ref/prepare.html

(2.1) By Larry Brasfield (LarryBrasfield) on 2020-04-14 01:17:57 edited from 2.0 in reply to 1 [link]

Re the plurality issue: The doc is consistent with the parameter name as spelled in the doc.  The fact that a formal parameter is declared and used with a different name is immaterial to the correctness of the documentation. (It specifies an interface, not implementation.)

Re code paths: I see that a different code path is taken when nBytes > 0 and nBytes does not include the null-terminator than when other conditions pertain.

Maybe there is a typo.  Is "nul-terminator" a word (or phrase)?

(3) By Matthew Mario Di Pasquale (ma11hew28) on 2020-04-14 15:27:25 in reply to 2.1

Thank you for responding, Larry.

Re the plurality issue: I'm sorry for not making myself clear and for not including the other reason I thought of. I meant that all occurrences of nByte in the doc page prepare.html should be changed to nBytes. Yes, I agree that the doc is consistent and correct the way it is, but I think nBytes is a bit more clear than nByte, not only because nBytes matches the name used in the source code but also because nBytes seems to be an abbreviation for the "number of bytes", not the "number of byte" or the "n<sup>th</sup> byte". I imagine nByte was updated to nBytes in the source code for this reason (and that the doc is outdated).

Re code paths: Yes, I see that too. And do you see that the same code path is taken whether nBytes is -1 or whether nBytes is the number of bytes in zSql plus one? Here's how I see it: If nBytes is -1, then `nBytes>=0` is false. And if, eg, zSql is "SELECT 1" and nBytes is 9 (since the number of characters in "SELECT 1" is 8 plus 1 to include the null character), then `zSql[nBytes-1]!=0` is false. So in either case the else block is executed. If my logic is correct, then maybe the doc sentence I quoted above should be removed or clarified.

Re the typo: Yeah, maybe "nul-terminator" should be "null terminator". And for consistency, maybe "zero terminator" should be "null terminator" and "nul-terminated" should be "null-terminated". I think there's supposed to be a space when it's used as a noun and a hyphen when it's used as an adjective.

(4) By Stephan Beal (stephan) on 2020-04-14 15:44:10 in reply to 3 [link]

> Re the typo: Yeah, maybe "nul-terminator" should be "null terminator". And for consistency, maybe "zero terminator" should be "null terminator" and "nul-terminated" should be "null-terminated".

NULL termination is not a real thing, but is a common typo. The proper term, in C at least, is NUL termination/NUL-terminated, as byte number zero is the "NUL byte" (the capitalization is just a matter of taste, though).

(5) By Richard Damon (RichardDamon) on 2020-04-14 15:56:12 in reply to 4 [link]

Or maybe more explicitly.

(In SQL) NULL is a database field value, indicating missing/omitted data.

(In C) A NULL-pointer is a pointer made by converting the constant 0 to a pointer and indicates that the pointer doesn't really point to anything

(In ASCII, and in C) NUL is the character value of 0, which is often used to terminate strings.

To have something NULL-terminated would be to have a list of pointers, the last one being a NULL-pointer.

(6) By Dan Kennedy (dan) on 2020-04-14 16:01:50 in reply to 3 [link]

Fair point - the same performance advantage obtained by passing (strlen(zSql)+1) for the nByte parameter may also be obtained by passing -1.

(7) By Matthew Mario Di Pasquale (ma11hew28) on 2020-04-14 18:28:54 in reply to 4 [link]

OK. Thank you, Stephan & Richard.

(8) By Matthew Mario Di Pasquale (ma11hew28) on 2020-04-14 18:30:10 in reply to 6 [link]

Great. Thank you for confirming that, Dan.