Implements stmt.named_params

[captn3m0]

Closes #627

Implemented named_params directly in C. Not a C programmer, mistakes are mine. Learned about @ and $ prefixes while reading the docs, so added them to the test as well.

However, this implementation ignores sqlite3_bind_parameter_index entirely, which is only used internally so shouldn't be an issue(?). As of now, the index of the parameter in the result might not match the value returned by sqlite3_bind_parameter_index in some cases.

But this feels better than having to pad the result with nulls.

Once this is finalized, I can update the changelog if needed

[captn3m0]

@flavorjones mind taking a look?

[flavorjones]

@captn3m0 Thanks for this! I've kicked off CI.

I'd like to see a test for the behavior of this code when given ?NNN parameters. Do you think the method should return those parameters? I'm not sure what happens if you try to bind a variable to a name like ?13.

[captn3m0]

I'm not sure what happens if you try to bind a variable to a name like ?13.

https://sqlite.org/forum/forumpost/533576942b17bf66 is the best explanation I could find.

? - means to use the next available parameter number that is one greater than any parameter number previously used starting at 1 if this is the first one.
?NNN - means parameter at location number NNN
?NNN (:VVV, @ VVV and $VVV are same) - means parameter at location number NNN.

Nothing special about 3 digits either, ?1 binds as the first param, and ?1111 happily binds as the 1111th parameter.

sqlite3_bind_parameter_name returns the numeric value itself as a string for these parameters. So this test passes on the current code:

stmt = SQLite3::Statement.new(@db, "select ?1")
stmt.bind_param(1, "foo")
assert_equal ["1"], stmt.named_params
stmt.each do |row|
  assert_equal ["foo"], row
end

My first thought is that these aren't really named parameters and we should just drop them. But then, if you were using a statement like: "select ?2, ?3", you'd be back to the same problem this PR is trying to solve for these ?NNN params - no way to discover the params based off just bind_parameter_count.

One way would be to return a mixed array? [2, "foo", "bar", 3], so that the values in the array can be directly used against bind_params. And perhaps change the name merely stmt.params.

[captn3m0]

Spent a bit more time at the problem, and it looks like the list bindable numbered params problem is unsolvable. The parameter_count is the max_index, and anything below that is considered bindable. For a statement like "SELECT ?, ?, ?50", you can bind all params from 1-50.

And there's no way to differentiate and get a result that says [1,2,50].

One way would be to return a mixed array? [2, "foo", "bar", 3], so that the values in the array can be directly used against bind_params. And perhaps change the name merely stmt.params.

I wrote this implementation, which works well as long as params are either numbered or named. Once you add anonymous params to the mix, it goes haywire.

Suggestion: named_params should only support really named params (which are alphanumeric tokens), and drop any numeric params. For those, a simple loop from 1-bind_parameter_count is the best you can do which is already support.

[captn3m0]

Pushed a change to ignore numeric and anonymous parameters:

stmt = SQLite3::Statement.new(@db, "select  ?1, :foo, ?, $bar, @zed, ?250, @999")
assert_equal ["foo", "bar", "zed"], stmt.named_params

[captn3m0]

Looked at the windows CI failures, but couldn't figure out why.

[flavorjones]

Please don't worry about the failing tests for windows and ruby 3.2, 3.3, and 3.4 -- they're failing for unrelated reasons.

I added some comments about support for named parameters that happen to be numeric.

This is looking good! I feel like it's really close, just the numeric edge case and I think we can merge it.

[captn3m0]

Thanks, will take a look and get back.

[captn3m0]

Update the FAQ alongside the code as well.

[flavorjones]

Rebased and added a commit with small changes to the docstring. I think this is ready to go, when it goes green I'll merge it.

[flavorjones]

Merged! Will be in v2.9.0 when it's released.