Array support with delimiter interface

[cbandy]

This adds types that implement driver.Valuer and sql.Scanner for arrays and slices.

There are a handful of "native" types that efficiently handle one-dimensional slices (e.g. StringArray for []string) and a "generic" type that uses reflection to traverse multi-dimensional arrays/slices.

The ArrayDelimiter interface can be implemented by a type that does not use comma as its delimiter. For example,

type Box struct { ... }
func (b Box) Value() (driver.Value, error) { ... }
func (b Box) ArrayDelimiter() string { return ";" }

The most convenient way to use these types is probably the Array function. It provides a consistent way to send and receive arrays and slices of various types. For example,

db.Query(..., pq.Array([]string{ ... }))
db.Query(..., pq.Array([][]int{ ... }))

var x []sql.NullInt64
var y []string
db.QueryRow(...).Scan(pq.Array(&x))
db.QueryRow(...).Scan(pq.Array(&y))

See also #49, #130, #327, #353, #364, #464.

[cbandy]

GenericArray.Scan() is artificially limited to handle only one-dimensional array/slice of sql.Scanner as discussed toward the end of #364. I simply ran out of time to handle all the possible combinations of types and dimensions. Fortunately, those limitations can be lifted (gradually, even) without changing the exported API in any way.

[freeformz]

@johto Any thoughts on this?

[johto]

I'll have a closer look at this over the weekend.

My memory isn't that great, but I thought there were serious issues discussed with these types of struct definitions in #364, which is why I suggested doing:

type Int64Array struct { A *[]int64 }

instead. Have those issues been fixed here?

[cbandy]

My memory isn't that great, but I thought there were serious issues discussed with these types of struct definitions

Have those issues been fixed here?

I think you're referring to things implementing both Scanner and Valuer. The Array function returns pointers to achieve this, e.g. return (*BoolArray)(&a). The GenericArray struct behaves as you've described.

Yes, I'd say those issues have been fixed.

[swsnider]

Any chance of this getting merged soon? I'm going to have to hold this patch in a private fork otherwise :(.

[ppeble]

+1 on merging. We would like to use this improvement in our internal projects.

[johto]

OK, I'm working on this right now.

[johto]

I've pushed this in 80f8150 after a number of changes. Most notably, I changed code like this:

func whatever(...) (err error) {
    elems, err := scanLinearArray(src, []byte{','}, "ByteaArray")

    switch {
    case err != nil:
        break

because it set off the "unintended shadowing" bells in my head really strongly. The spec says the "err" here redeclares the one in the parameter list of the result specification of the function, but it's not obvious to the reader -- I had to literally open the spec to see what the behavior should be, and I consider myself fairly experienced as a Go developer. I also changed a number of if statements masquerading as switches. Some of them were hurting readability seriously, some of them just felt icky.

I'm also really not happy with the way parseArray is written right now. It's a big non-obvious mess of goto spaghetti, and I had to read several blocks of it more than three times to understand what was really going on. It should be rewritten using recursion instead (perhaps passing around a small struct with the parse state), but I didn't do that now. I have other things to do today.

I also added documentation about the lack of support for scanning of multi-dimensional arrays and arrays with unorthodox bounds.

[ppeble]

Thank you @johto!

[cbandy]

@johto, thank you for reviewing and merging this. A lot of people expressed interest, but you're the only one to comment on the actual patches here. Thank you for taking care of the issues with shadowing and readability.

It wasn't my intention to leave you with code that you find hard to maintain. I want my contributions to this project to positive for both users and maintainers alike. I'm sorry for leaving this branch open for so long and I'm sorry if I haven't seemed open to feedback.

Also, thank you to @erykwalder. This is absolutely based on your work in #353 I had forgotten how many of your suggestions in #364 I had incorporated here.