Source file src/github.com/jackc/pgx/v5/pgtype/pgtype.go

Documentation: github.com/jackc/pgx/v5/pgtype

     1  package pgtype
     2  
     3  import (
     4  	"database/sql"
     5  	"database/sql/driver"
     6  	"errors"
     7  	"fmt"
     8  	"net"
     9  	"net/netip"
    10  	"reflect"
    11  	"time"
    12  )
    13  
    14  // PostgreSQL oids for common types
    15  const (
    16  	BoolOID                = 16
    17  	ByteaOID               = 17
    18  	QCharOID               = 18
    19  	NameOID                = 19
    20  	Int8OID                = 20
    21  	Int2OID                = 21
    22  	Int4OID                = 23
    23  	TextOID                = 25
    24  	OIDOID                 = 26
    25  	TIDOID                 = 27
    26  	XIDOID                 = 28
    27  	CIDOID                 = 29
    28  	JSONOID                = 114
    29  	JSONArrayOID           = 199
    30  	PointOID               = 600
    31  	LsegOID                = 601
    32  	PathOID                = 602
    33  	BoxOID                 = 603
    34  	PolygonOID             = 604
    35  	LineOID                = 628
    36  	LineArrayOID           = 629
    37  	CIDROID                = 650
    38  	CIDRArrayOID           = 651
    39  	Float4OID              = 700
    40  	Float8OID              = 701
    41  	CircleOID              = 718
    42  	CircleArrayOID         = 719
    43  	UnknownOID             = 705
    44  	MacaddrOID             = 829
    45  	InetOID                = 869
    46  	BoolArrayOID           = 1000
    47  	QCharArrayOID          = 1002
    48  	NameArrayOID           = 1003
    49  	Int2ArrayOID           = 1005
    50  	Int4ArrayOID           = 1007
    51  	TextArrayOID           = 1009
    52  	TIDArrayOID            = 1010
    53  	ByteaArrayOID          = 1001
    54  	XIDArrayOID            = 1011
    55  	CIDArrayOID            = 1012
    56  	BPCharArrayOID         = 1014
    57  	VarcharArrayOID        = 1015
    58  	Int8ArrayOID           = 1016
    59  	PointArrayOID          = 1017
    60  	LsegArrayOID           = 1018
    61  	PathArrayOID           = 1019
    62  	BoxArrayOID            = 1020
    63  	Float4ArrayOID         = 1021
    64  	Float8ArrayOID         = 1022
    65  	PolygonArrayOID        = 1027
    66  	OIDArrayOID            = 1028
    67  	ACLItemOID             = 1033
    68  	ACLItemArrayOID        = 1034
    69  	MacaddrArrayOID        = 1040
    70  	InetArrayOID           = 1041
    71  	BPCharOID              = 1042
    72  	VarcharOID             = 1043
    73  	DateOID                = 1082
    74  	TimeOID                = 1083
    75  	TimestampOID           = 1114
    76  	TimestampArrayOID      = 1115
    77  	DateArrayOID           = 1182
    78  	TimeArrayOID           = 1183
    79  	TimestamptzOID         = 1184
    80  	TimestamptzArrayOID    = 1185
    81  	IntervalOID            = 1186
    82  	IntervalArrayOID       = 1187
    83  	NumericArrayOID        = 1231
    84  	TimetzOID              = 1266
    85  	TimetzArrayOID         = 1270
    86  	BitOID                 = 1560
    87  	BitArrayOID            = 1561
    88  	VarbitOID              = 1562
    89  	VarbitArrayOID         = 1563
    90  	NumericOID             = 1700
    91  	RecordOID              = 2249
    92  	RecordArrayOID         = 2287
    93  	UUIDOID                = 2950
    94  	UUIDArrayOID           = 2951
    95  	JSONBOID               = 3802
    96  	JSONBArrayOID          = 3807
    97  	DaterangeOID           = 3912
    98  	DaterangeArrayOID      = 3913
    99  	Int4rangeOID           = 3904
   100  	Int4rangeArrayOID      = 3905
   101  	NumrangeOID            = 3906
   102  	NumrangeArrayOID       = 3907
   103  	TsrangeOID             = 3908
   104  	TsrangeArrayOID        = 3909
   105  	TstzrangeOID           = 3910
   106  	TstzrangeArrayOID      = 3911
   107  	Int8rangeOID           = 3926
   108  	Int8rangeArrayOID      = 3927
   109  	JSONPathOID            = 4072
   110  	JSONPathArrayOID       = 4073
   111  	Int4multirangeOID      = 4451
   112  	NummultirangeOID       = 4532
   113  	TsmultirangeOID        = 4533
   114  	TstzmultirangeOID      = 4534
   115  	DatemultirangeOID      = 4535
   116  	Int8multirangeOID      = 4536
   117  	Int4multirangeArrayOID = 6150
   118  	NummultirangeArrayOID  = 6151
   119  	TsmultirangeArrayOID   = 6152
   120  	TstzmultirangeArrayOID = 6153
   121  	DatemultirangeArrayOID = 6155
   122  	Int8multirangeArrayOID = 6157
   123  )
   124  
   125  type InfinityModifier int8
   126  
   127  const (
   128  	Infinity         InfinityModifier = 1
   129  	Finite           InfinityModifier = 0
   130  	NegativeInfinity InfinityModifier = -Infinity
   131  )
   132  
   133  func (im InfinityModifier) String() string {
   134  	switch im {
   135  	case Finite:
   136  		return "finite"
   137  	case Infinity:
   138  		return "infinity"
   139  	case NegativeInfinity:
   140  		return "-infinity"
   141  	default:
   142  		return "invalid"
   143  	}
   144  }
   145  
   146  // PostgreSQL format codes
   147  const (
   148  	TextFormatCode   = 0
   149  	BinaryFormatCode = 1
   150  )
   151  
   152  // A Codec converts between Go and PostgreSQL values. A Codec must not be mutated after it is registered with a Map.
   153  type Codec interface {
   154  	// FormatSupported returns true if the format is supported.
   155  	FormatSupported(int16) bool
   156  
   157  	// PreferredFormat returns the preferred format.
   158  	PreferredFormat() int16
   159  
   160  	// PlanEncode returns an EncodePlan for encoding value into PostgreSQL format for oid and format. If no plan can be
   161  	// found then nil is returned.
   162  	PlanEncode(m *Map, oid uint32, format int16, value any) EncodePlan
   163  
   164  	// PlanScan returns a ScanPlan for scanning a PostgreSQL value into a destination with the same type as target. If
   165  	// no plan can be found then nil is returned.
   166  	PlanScan(m *Map, oid uint32, format int16, target any) ScanPlan
   167  
   168  	// DecodeDatabaseSQLValue returns src decoded into a value compatible with the sql.Scanner interface.
   169  	DecodeDatabaseSQLValue(m *Map, oid uint32, format int16, src []byte) (driver.Value, error)
   170  
   171  	// DecodeValue returns src decoded into its default format.
   172  	DecodeValue(m *Map, oid uint32, format int16, src []byte) (any, error)
   173  }
   174  
   175  type nullAssignmentError struct {
   176  	dst any
   177  }
   178  
   179  func (e *nullAssignmentError) Error() string {
   180  	return fmt.Sprintf("cannot assign NULL to %T", e.dst)
   181  }
   182  
   183  // Type represents a PostgreSQL data type. It must not be mutated after it is registered with a Map.
   184  type Type struct {
   185  	Codec Codec
   186  	Name  string
   187  	OID   uint32
   188  }
   189  
   190  // Map is the mapping between PostgreSQL server types and Go type handling logic. It can encode values for
   191  // transmission to a PostgreSQL server and scan received values.
   192  type Map struct {
   193  	oidToType         map[uint32]*Type
   194  	nameToType        map[string]*Type
   195  	reflectTypeToName map[reflect.Type]string
   196  	oidToFormatCode   map[uint32]int16
   197  
   198  	reflectTypeToType map[reflect.Type]*Type
   199  
   200  	memoizedScanPlans   map[uint32]map[reflect.Type][2]ScanPlan
   201  	memoizedEncodePlans map[uint32]map[reflect.Type][2]EncodePlan
   202  
   203  	// TryWrapEncodePlanFuncs is a slice of functions that will wrap a value that cannot be encoded by the Codec. Every
   204  	// time a wrapper is found the PlanEncode method will be recursively called with the new value. This allows several layers of wrappers
   205  	// to be built up. There are default functions placed in this slice by NewMap(). In most cases these functions
   206  	// should run last. i.e. Additional functions should typically be prepended not appended.
   207  	TryWrapEncodePlanFuncs []TryWrapEncodePlanFunc
   208  
   209  	// TryWrapScanPlanFuncs is a slice of functions that will wrap a target that cannot be scanned into by the Codec. Every
   210  	// time a wrapper is found the PlanScan method will be recursively called with the new target. This allows several layers of wrappers
   211  	// to be built up. There are default functions placed in this slice by NewMap(). In most cases these functions
   212  	// should run last. i.e. Additional functions should typically be prepended not appended.
   213  	TryWrapScanPlanFuncs []TryWrapScanPlanFunc
   214  }
   215  
   216  func NewMap() *Map {
   217  	defaultMapInitOnce.Do(initDefaultMap)
   218  
   219  	return &Map{
   220  		oidToType:         make(map[uint32]*Type),
   221  		nameToType:        make(map[string]*Type),
   222  		reflectTypeToName: make(map[reflect.Type]string),
   223  		oidToFormatCode:   make(map[uint32]int16),
   224  
   225  		memoizedScanPlans:   make(map[uint32]map[reflect.Type][2]ScanPlan),
   226  		memoizedEncodePlans: make(map[uint32]map[reflect.Type][2]EncodePlan),
   227  
   228  		TryWrapEncodePlanFuncs: []TryWrapEncodePlanFunc{
   229  			TryWrapDerefPointerEncodePlan,
   230  			TryWrapBuiltinTypeEncodePlan,
   231  			TryWrapFindUnderlyingTypeEncodePlan,
   232  			TryWrapStructEncodePlan,
   233  			TryWrapSliceEncodePlan,
   234  			TryWrapMultiDimSliceEncodePlan,
   235  			TryWrapArrayEncodePlan,
   236  		},
   237  
   238  		TryWrapScanPlanFuncs: []TryWrapScanPlanFunc{
   239  			TryPointerPointerScanPlan,
   240  			TryWrapBuiltinTypeScanPlan,
   241  			TryFindUnderlyingTypeScanPlan,
   242  			TryWrapStructScanPlan,
   243  			TryWrapPtrSliceScanPlan,
   244  			TryWrapPtrMultiDimSliceScanPlan,
   245  			TryWrapPtrArrayScanPlan,
   246  		},
   247  	}
   248  }
   249  
   250  // RegisterType registers a data type with the Map. t must not be mutated after it is registered.
   251  func (m *Map) RegisterType(t *Type) {
   252  	m.oidToType[t.OID] = t
   253  	m.nameToType[t.Name] = t
   254  	m.oidToFormatCode[t.OID] = t.Codec.PreferredFormat()
   255  
   256  	// Invalidated by type registration
   257  	m.reflectTypeToType = nil
   258  	for k := range m.memoizedScanPlans {
   259  		delete(m.memoizedScanPlans, k)
   260  	}
   261  	for k := range m.memoizedEncodePlans {
   262  		delete(m.memoizedEncodePlans, k)
   263  	}
   264  }
   265  
   266  // RegisterDefaultPgType registers a mapping of a Go type to a PostgreSQL type name. Typically the data type to be
   267  // encoded or decoded is determined by the PostgreSQL OID. But if the OID of a value to be encoded or decoded is
   268  // unknown, this additional mapping will be used by TypeForValue to determine a suitable data type.
   269  func (m *Map) RegisterDefaultPgType(value any, name string) {
   270  	m.reflectTypeToName[reflect.TypeOf(value)] = name
   271  
   272  	// Invalidated by type registration
   273  	m.reflectTypeToType = nil
   274  	for k := range m.memoizedScanPlans {
   275  		delete(m.memoizedScanPlans, k)
   276  	}
   277  	for k := range m.memoizedEncodePlans {
   278  		delete(m.memoizedEncodePlans, k)
   279  	}
   280  }
   281  
   282  // TypeForOID returns the Type registered for the given OID. The returned Type must not be mutated.
   283  func (m *Map) TypeForOID(oid uint32) (*Type, bool) {
   284  	if dt, ok := m.oidToType[oid]; ok {
   285  		return dt, true
   286  	}
   287  
   288  	dt, ok := defaultMap.oidToType[oid]
   289  	return dt, ok
   290  }
   291  
   292  // TypeForName returns the Type registered for the given name. The returned Type must not be mutated.
   293  func (m *Map) TypeForName(name string) (*Type, bool) {
   294  	if dt, ok := m.nameToType[name]; ok {
   295  		return dt, true
   296  	}
   297  	dt, ok := defaultMap.nameToType[name]
   298  	return dt, ok
   299  }
   300  
   301  func (m *Map) buildReflectTypeToType() {
   302  	m.reflectTypeToType = make(map[reflect.Type]*Type)
   303  
   304  	for reflectType, name := range m.reflectTypeToName {
   305  		if dt, ok := m.TypeForName(name); ok {
   306  			m.reflectTypeToType[reflectType] = dt
   307  		}
   308  	}
   309  }
   310  
   311  // TypeForValue finds a data type suitable for v. Use RegisterType to register types that can encode and decode
   312  // themselves. Use RegisterDefaultPgType to register that can be handled by a registered data type.  The returned Type
   313  // must not be mutated.
   314  func (m *Map) TypeForValue(v any) (*Type, bool) {
   315  	if m.reflectTypeToType == nil {
   316  		m.buildReflectTypeToType()
   317  	}
   318  
   319  	if dt, ok := m.reflectTypeToType[reflect.TypeOf(v)]; ok {
   320  		return dt, true
   321  	}
   322  
   323  	dt, ok := defaultMap.reflectTypeToType[reflect.TypeOf(v)]
   324  	return dt, ok
   325  }
   326  
   327  // FormatCodeForOID returns the preferred format code for type oid. If the type is not registered it returns the text
   328  // format code.
   329  func (m *Map) FormatCodeForOID(oid uint32) int16 {
   330  	if fc, ok := m.oidToFormatCode[oid]; ok {
   331  		return fc
   332  	}
   333  
   334  	if fc, ok := defaultMap.oidToFormatCode[oid]; ok {
   335  		return fc
   336  	}
   337  
   338  	return TextFormatCode
   339  }
   340  
   341  // EncodePlan is a precompiled plan to encode a particular type into a particular OID and format.
   342  type EncodePlan interface {
   343  	// Encode appends the encoded bytes of value to buf. If value is the SQL value NULL then append nothing and return
   344  	// (nil, nil). The caller of Encode is responsible for writing the correct NULL value or the length of the data
   345  	// written.
   346  	Encode(value any, buf []byte) (newBuf []byte, err error)
   347  }
   348  
   349  // ScanPlan is a precompiled plan to scan into a type of destination.
   350  type ScanPlan interface {
   351  	// Scan scans src into target. src is only valid during the call to Scan. The ScanPlan must not retain a reference to
   352  	// src.
   353  	Scan(src []byte, target any) error
   354  }
   355  
   356  type scanPlanCodecSQLScanner struct {
   357  	c          Codec
   358  	m          *Map
   359  	oid        uint32
   360  	formatCode int16
   361  }
   362  
   363  func (plan *scanPlanCodecSQLScanner) Scan(src []byte, dst any) error {
   364  	value, err := plan.c.DecodeDatabaseSQLValue(plan.m, plan.oid, plan.formatCode, src)
   365  	if err != nil {
   366  		return err
   367  	}
   368  
   369  	scanner := dst.(sql.Scanner)
   370  	return scanner.Scan(value)
   371  }
   372  
   373  type scanPlanSQLScanner struct {
   374  	formatCode int16
   375  }
   376  
   377  func (plan *scanPlanSQLScanner) Scan(src []byte, dst any) error {
   378  	scanner := dst.(sql.Scanner)
   379  	if src == nil {
   380  		// This is necessary because interface value []byte:nil does not equal nil:nil for the binary format path and the
   381  		// text format path would be converted to empty string.
   382  		return scanner.Scan(nil)
   383  	} else if plan.formatCode == BinaryFormatCode {
   384  		return scanner.Scan(src)
   385  	} else {
   386  		return scanner.Scan(string(src))
   387  	}
   388  }
   389  
   390  type scanPlanString struct{}
   391  
   392  func (scanPlanString) Scan(src []byte, dst any) error {
   393  	if src == nil {
   394  		return fmt.Errorf("cannot scan NULL into %T", dst)
   395  	}
   396  
   397  	p := (dst).(*string)
   398  	*p = string(src)
   399  	return nil
   400  }
   401  
   402  type scanPlanAnyTextToBytes struct{}
   403  
   404  func (scanPlanAnyTextToBytes) Scan(src []byte, dst any) error {
   405  	dstBuf := dst.(*[]byte)
   406  	if src == nil {
   407  		*dstBuf = nil
   408  		return nil
   409  	}
   410  
   411  	*dstBuf = make([]byte, len(src))
   412  	copy(*dstBuf, src)
   413  	return nil
   414  }
   415  
   416  type scanPlanFail struct {
   417  	m          *Map
   418  	oid        uint32
   419  	formatCode int16
   420  }
   421  
   422  func (plan *scanPlanFail) Scan(src []byte, dst any) error {
   423  	// If src is NULL it might be possible to scan into dst even though it is the types are not compatible. While this
   424  	// may seem to be a contrived case it can occur when selecting NULL directly. PostgreSQL assigns it the type of text.
   425  	// It would be surprising to the caller to have to cast the NULL (e.g. `select null::int`). So try to figure out a
   426  	// compatible data type for dst and scan with that.
   427  	//
   428  	// See https://github.com/jackc/pgx/issues/1326
   429  	if src == nil {
   430  		// As a horrible hack try all types to find anything that can scan into dst.
   431  		for oid := range plan.m.oidToType {
   432  			// using planScan instead of Scan or PlanScan to avoid polluting the planned scan cache.
   433  			plan := plan.m.planScan(oid, plan.formatCode, dst)
   434  			if _, ok := plan.(*scanPlanFail); !ok {
   435  				return plan.Scan(src, dst)
   436  			}
   437  		}
   438  		for oid := range defaultMap.oidToType {
   439  			if _, ok := plan.m.oidToType[oid]; !ok {
   440  				plan := plan.m.planScan(oid, plan.formatCode, dst)
   441  				if _, ok := plan.(*scanPlanFail); !ok {
   442  					return plan.Scan(src, dst)
   443  				}
   444  			}
   445  		}
   446  	}
   447  
   448  	var format string
   449  	switch plan.formatCode {
   450  	case TextFormatCode:
   451  		format = "text"
   452  	case BinaryFormatCode:
   453  		format = "binary"
   454  	default:
   455  		format = fmt.Sprintf("unknown %d", plan.formatCode)
   456  	}
   457  
   458  	var dataTypeName string
   459  	if t, ok := plan.m.TypeForOID(plan.oid); ok {
   460  		dataTypeName = t.Name
   461  	} else {
   462  		dataTypeName = "unknown type"
   463  	}
   464  
   465  	return fmt.Errorf("cannot scan %s (OID %d) in %v format into %T", dataTypeName, plan.oid, format, dst)
   466  }
   467  
   468  // TryWrapScanPlanFunc is a function that tries to create a wrapper plan for target. If successful it returns a plan
   469  // that will convert the target passed to Scan and then call the next plan. nextTarget is target as it will be converted
   470  // by plan. It must be used to find another suitable ScanPlan. When it is found SetNext must be called on plan for it
   471  // to be usabled. ok indicates if a suitable wrapper was found.
   472  type TryWrapScanPlanFunc func(target any) (plan WrappedScanPlanNextSetter, nextTarget any, ok bool)
   473  
   474  type pointerPointerScanPlan struct {
   475  	dstType reflect.Type
   476  	next    ScanPlan
   477  }
   478  
   479  func (plan *pointerPointerScanPlan) SetNext(next ScanPlan) { plan.next = next }
   480  
   481  func (plan *pointerPointerScanPlan) Scan(src []byte, dst any) error {
   482  	el := reflect.ValueOf(dst).Elem()
   483  	if src == nil {
   484  		el.Set(reflect.Zero(el.Type()))
   485  		return nil
   486  	}
   487  
   488  	el.Set(reflect.New(el.Type().Elem()))
   489  	return plan.next.Scan(src, el.Interface())
   490  }
   491  
   492  // TryPointerPointerScanPlan handles a pointer to a pointer by setting the target to nil for SQL NULL and allocating and
   493  // scanning for non-NULL.
   494  func TryPointerPointerScanPlan(target any) (plan WrappedScanPlanNextSetter, nextTarget any, ok bool) {
   495  	if dstValue := reflect.ValueOf(target); dstValue.Kind() == reflect.Ptr {
   496  		elemValue := dstValue.Elem()
   497  		if elemValue.Kind() == reflect.Ptr {
   498  			plan = &pointerPointerScanPlan{dstType: dstValue.Type()}
   499  			return plan, reflect.Zero(elemValue.Type()).Interface(), true
   500  		}
   501  	}
   502  
   503  	return nil, nil, false
   504  }
   505  
   506  // SkipUnderlyingTypePlanner prevents PlanScan and PlanDecode from trying to use the underlying type.
   507  type SkipUnderlyingTypePlanner interface {
   508  	SkipUnderlyingTypePlan()
   509  }
   510  
   511  var elemKindToPointerTypes map[reflect.Kind]reflect.Type = map[reflect.Kind]reflect.Type{
   512  	reflect.Int:     reflect.TypeOf(new(int)),
   513  	reflect.Int8:    reflect.TypeOf(new(int8)),
   514  	reflect.Int16:   reflect.TypeOf(new(int16)),
   515  	reflect.Int32:   reflect.TypeOf(new(int32)),
   516  	reflect.Int64:   reflect.TypeOf(new(int64)),
   517  	reflect.Uint:    reflect.TypeOf(new(uint)),
   518  	reflect.Uint8:   reflect.TypeOf(new(uint8)),
   519  	reflect.Uint16:  reflect.TypeOf(new(uint16)),
   520  	reflect.Uint32:  reflect.TypeOf(new(uint32)),
   521  	reflect.Uint64:  reflect.TypeOf(new(uint64)),
   522  	reflect.Float32: reflect.TypeOf(new(float32)),
   523  	reflect.Float64: reflect.TypeOf(new(float64)),
   524  	reflect.String:  reflect.TypeOf(new(string)),
   525  	reflect.Bool:    reflect.TypeOf(new(bool)),
   526  }
   527  
   528  type underlyingTypeScanPlan struct {
   529  	dstType     reflect.Type
   530  	nextDstType reflect.Type
   531  	next        ScanPlan
   532  }
   533  
   534  func (plan *underlyingTypeScanPlan) SetNext(next ScanPlan) { plan.next = next }
   535  
   536  func (plan *underlyingTypeScanPlan) Scan(src []byte, dst any) error {
   537  	return plan.next.Scan(src, reflect.ValueOf(dst).Convert(plan.nextDstType).Interface())
   538  }
   539  
   540  // TryFindUnderlyingTypeScanPlan tries to convert to a Go builtin type. e.g. If value was of type MyString and
   541  // MyString was defined as a string then a wrapper plan would be returned that converts MyString to string.
   542  func TryFindUnderlyingTypeScanPlan(dst any) (plan WrappedScanPlanNextSetter, nextDst any, ok bool) {
   543  	if _, ok := dst.(SkipUnderlyingTypePlanner); ok {
   544  		return nil, nil, false
   545  	}
   546  
   547  	dstValue := reflect.ValueOf(dst)
   548  
   549  	if dstValue.Kind() == reflect.Ptr {
   550  		var elemValue reflect.Value
   551  		if dstValue.IsNil() {
   552  			elemValue = reflect.New(dstValue.Type().Elem()).Elem()
   553  		} else {
   554  			elemValue = dstValue.Elem()
   555  		}
   556  		nextDstType := elemKindToPointerTypes[elemValue.Kind()]
   557  		if nextDstType == nil && elemValue.Kind() == reflect.Slice {
   558  			if elemValue.Type().Elem().Kind() == reflect.Uint8 {
   559  				var v *[]byte
   560  				nextDstType = reflect.TypeOf(v)
   561  			}
   562  		}
   563  
   564  		if nextDstType != nil && dstValue.Type() != nextDstType && dstValue.CanConvert(nextDstType) {
   565  			return &underlyingTypeScanPlan{dstType: dstValue.Type(), nextDstType: nextDstType}, dstValue.Convert(nextDstType).Interface(), true
   566  		}
   567  
   568  	}
   569  
   570  	return nil, nil, false
   571  }
   572  
   573  type WrappedScanPlanNextSetter interface {
   574  	SetNext(ScanPlan)
   575  	ScanPlan
   576  }
   577  
   578  // TryWrapBuiltinTypeScanPlan tries to wrap a builtin type with a wrapper that provides additional methods. e.g. If
   579  // value was of type int32 then a wrapper plan would be returned that converts target to a value that implements
   580  // Int64Scanner.
   581  func TryWrapBuiltinTypeScanPlan(target any) (plan WrappedScanPlanNextSetter, nextDst any, ok bool) {
   582  	switch target := target.(type) {
   583  	case *int8:
   584  		return &wrapInt8ScanPlan{}, (*int8Wrapper)(target), true
   585  	case *int16:
   586  		return &wrapInt16ScanPlan{}, (*int16Wrapper)(target), true
   587  	case *int32:
   588  		return &wrapInt32ScanPlan{}, (*int32Wrapper)(target), true
   589  	case *int64:
   590  		return &wrapInt64ScanPlan{}, (*int64Wrapper)(target), true
   591  	case *int:
   592  		return &wrapIntScanPlan{}, (*intWrapper)(target), true
   593  	case *uint8:
   594  		return &wrapUint8ScanPlan{}, (*uint8Wrapper)(target), true
   595  	case *uint16:
   596  		return &wrapUint16ScanPlan{}, (*uint16Wrapper)(target), true
   597  	case *uint32:
   598  		return &wrapUint32ScanPlan{}, (*uint32Wrapper)(target), true
   599  	case *uint64:
   600  		return &wrapUint64ScanPlan{}, (*uint64Wrapper)(target), true
   601  	case *uint:
   602  		return &wrapUintScanPlan{}, (*uintWrapper)(target), true
   603  	case *float32:
   604  		return &wrapFloat32ScanPlan{}, (*float32Wrapper)(target), true
   605  	case *float64:
   606  		return &wrapFloat64ScanPlan{}, (*float64Wrapper)(target), true
   607  	case *string:
   608  		return &wrapStringScanPlan{}, (*stringWrapper)(target), true
   609  	case *time.Time:
   610  		return &wrapTimeScanPlan{}, (*timeWrapper)(target), true
   611  	case *time.Duration:
   612  		return &wrapDurationScanPlan{}, (*durationWrapper)(target), true
   613  	case *net.IPNet:
   614  		return &wrapNetIPNetScanPlan{}, (*netIPNetWrapper)(target), true
   615  	case *net.IP:
   616  		return &wrapNetIPScanPlan{}, (*netIPWrapper)(target), true
   617  	case *netip.Prefix:
   618  		return &wrapNetipPrefixScanPlan{}, (*netipPrefixWrapper)(target), true
   619  	case *netip.Addr:
   620  		return &wrapNetipAddrScanPlan{}, (*netipAddrWrapper)(target), true
   621  	case *map[string]*string:
   622  		return &wrapMapStringToPointerStringScanPlan{}, (*mapStringToPointerStringWrapper)(target), true
   623  	case *map[string]string:
   624  		return &wrapMapStringToStringScanPlan{}, (*mapStringToStringWrapper)(target), true
   625  	case *[16]byte:
   626  		return &wrapByte16ScanPlan{}, (*byte16Wrapper)(target), true
   627  	case *[]byte:
   628  		return &wrapByteSliceScanPlan{}, (*byteSliceWrapper)(target), true
   629  	}
   630  
   631  	return nil, nil, false
   632  }
   633  
   634  type wrapInt8ScanPlan struct {
   635  	next ScanPlan
   636  }
   637  
   638  func (plan *wrapInt8ScanPlan) SetNext(next ScanPlan) { plan.next = next }
   639  
   640  func (plan *wrapInt8ScanPlan) Scan(src []byte, dst any) error {
   641  	return plan.next.Scan(src, (*int8Wrapper)(dst.(*int8)))
   642  }
   643  
   644  type wrapInt16ScanPlan struct {
   645  	next ScanPlan
   646  }
   647  
   648  func (plan *wrapInt16ScanPlan) SetNext(next ScanPlan) { plan.next = next }
   649  
   650  func (plan *wrapInt16ScanPlan) Scan(src []byte, dst any) error {
   651  	return plan.next.Scan(src, (*int16Wrapper)(dst.(*int16)))
   652  }
   653  
   654  type wrapInt32ScanPlan struct {
   655  	next ScanPlan
   656  }
   657  
   658  func (plan *wrapInt32ScanPlan) SetNext(next ScanPlan) { plan.next = next }
   659  
   660  func (plan *wrapInt32ScanPlan) Scan(src []byte, dst any) error {
   661  	return plan.next.Scan(src, (*int32Wrapper)(dst.(*int32)))
   662  }
   663  
   664  type wrapInt64ScanPlan struct {
   665  	next ScanPlan
   666  }
   667  
   668  func (plan *wrapInt64ScanPlan) SetNext(next ScanPlan) { plan.next = next }
   669  
   670  func (plan *wrapInt64ScanPlan) Scan(src []byte, dst any) error {
   671  	return plan.next.Scan(src, (*int64Wrapper)(dst.(*int64)))
   672  }
   673  
   674  type wrapIntScanPlan struct {
   675  	next ScanPlan
   676  }
   677  
   678  func (plan *wrapIntScanPlan) SetNext(next ScanPlan) { plan.next = next }
   679  
   680  func (plan *wrapIntScanPlan) Scan(src []byte, dst any) error {
   681  	return plan.next.Scan(src, (*intWrapper)(dst.(*int)))
   682  }
   683  
   684  type wrapUint8ScanPlan struct {
   685  	next ScanPlan
   686  }
   687  
   688  func (plan *wrapUint8ScanPlan) SetNext(next ScanPlan) { plan.next = next }
   689  
   690  func (plan *wrapUint8ScanPlan) Scan(src []byte, dst any) error {
   691  	return plan.next.Scan(src, (*uint8Wrapper)(dst.(*uint8)))
   692  }
   693  
   694  type wrapUint16ScanPlan struct {
   695  	next ScanPlan
   696  }
   697  
   698  func (plan *wrapUint16ScanPlan) SetNext(next ScanPlan) { plan.next = next }
   699  
   700  func (plan *wrapUint16ScanPlan) Scan(src []byte, dst any) error {
   701  	return plan.next.Scan(src, (*uint16Wrapper)(dst.(*uint16)))
   702  }
   703  
   704  type wrapUint32ScanPlan struct {
   705  	next ScanPlan
   706  }
   707  
   708  func (plan *wrapUint32ScanPlan) SetNext(next ScanPlan) { plan.next = next }
   709  
   710  func (plan *wrapUint32ScanPlan) Scan(src []byte, dst any) error {
   711  	return plan.next.Scan(src, (*uint32Wrapper)(dst.(*uint32)))
   712  }
   713  
   714  type wrapUint64ScanPlan struct {
   715  	next ScanPlan
   716  }
   717  
   718  func (plan *wrapUint64ScanPlan) SetNext(next ScanPlan) { plan.next = next }
   719  
   720  func (plan *wrapUint64ScanPlan) Scan(src []byte, dst any) error {
   721  	return plan.next.Scan(src, (*uint64Wrapper)(dst.(*uint64)))
   722  }
   723  
   724  type wrapUintScanPlan struct {
   725  	next ScanPlan
   726  }
   727  
   728  func (plan *wrapUintScanPlan) SetNext(next ScanPlan) { plan.next = next }
   729  
   730  func (plan *wrapUintScanPlan) Scan(src []byte, dst any) error {
   731  	return plan.next.Scan(src, (*uintWrapper)(dst.(*uint)))
   732  }
   733  
   734  type wrapFloat32ScanPlan struct {
   735  	next ScanPlan
   736  }
   737  
   738  func (plan *wrapFloat32ScanPlan) SetNext(next ScanPlan) { plan.next = next }
   739  
   740  func (plan *wrapFloat32ScanPlan) Scan(src []byte, dst any) error {
   741  	return plan.next.Scan(src, (*float32Wrapper)(dst.(*float32)))
   742  }
   743  
   744  type wrapFloat64ScanPlan struct {
   745  	next ScanPlan
   746  }
   747  
   748  func (plan *wrapFloat64ScanPlan) SetNext(next ScanPlan) { plan.next = next }
   749  
   750  func (plan *wrapFloat64ScanPlan) Scan(src []byte, dst any) error {
   751  	return plan.next.Scan(src, (*float64Wrapper)(dst.(*float64)))
   752  }
   753  
   754  type wrapStringScanPlan struct {
   755  	next ScanPlan
   756  }
   757  
   758  func (plan *wrapStringScanPlan) SetNext(next ScanPlan) { plan.next = next }
   759  
   760  func (plan *wrapStringScanPlan) Scan(src []byte, dst any) error {
   761  	return plan.next.Scan(src, (*stringWrapper)(dst.(*string)))
   762  }
   763  
   764  type wrapTimeScanPlan struct {
   765  	next ScanPlan
   766  }
   767  
   768  func (plan *wrapTimeScanPlan) SetNext(next ScanPlan) { plan.next = next }
   769  
   770  func (plan *wrapTimeScanPlan) Scan(src []byte, dst any) error {
   771  	return plan.next.Scan(src, (*timeWrapper)(dst.(*time.Time)))
   772  }
   773  
   774  type wrapDurationScanPlan struct {
   775  	next ScanPlan
   776  }
   777  
   778  func (plan *wrapDurationScanPlan) SetNext(next ScanPlan) { plan.next = next }
   779  
   780  func (plan *wrapDurationScanPlan) Scan(src []byte, dst any) error {
   781  	return plan.next.Scan(src, (*durationWrapper)(dst.(*time.Duration)))
   782  }
   783  
   784  type wrapNetIPNetScanPlan struct {
   785  	next ScanPlan
   786  }
   787  
   788  func (plan *wrapNetIPNetScanPlan) SetNext(next ScanPlan) { plan.next = next }
   789  
   790  func (plan *wrapNetIPNetScanPlan) Scan(src []byte, dst any) error {
   791  	return plan.next.Scan(src, (*netIPNetWrapper)(dst.(*net.IPNet)))
   792  }
   793  
   794  type wrapNetIPScanPlan struct {
   795  	next ScanPlan
   796  }
   797  
   798  func (plan *wrapNetIPScanPlan) SetNext(next ScanPlan) { plan.next = next }
   799  
   800  func (plan *wrapNetIPScanPlan) Scan(src []byte, dst any) error {
   801  	return plan.next.Scan(src, (*netIPWrapper)(dst.(*net.IP)))
   802  }
   803  
   804  type wrapNetipPrefixScanPlan struct {
   805  	next ScanPlan
   806  }
   807  
   808  func (plan *wrapNetipPrefixScanPlan) SetNext(next ScanPlan) { plan.next = next }
   809  
   810  func (plan *wrapNetipPrefixScanPlan) Scan(src []byte, dst any) error {
   811  	return plan.next.Scan(src, (*netipPrefixWrapper)(dst.(*netip.Prefix)))
   812  }
   813  
   814  type wrapNetipAddrScanPlan struct {
   815  	next ScanPlan
   816  }
   817  
   818  func (plan *wrapNetipAddrScanPlan) SetNext(next ScanPlan) { plan.next = next }
   819  
   820  func (plan *wrapNetipAddrScanPlan) Scan(src []byte, dst any) error {
   821  	return plan.next.Scan(src, (*netipAddrWrapper)(dst.(*netip.Addr)))
   822  }
   823  
   824  type wrapMapStringToPointerStringScanPlan struct {
   825  	next ScanPlan
   826  }
   827  
   828  func (plan *wrapMapStringToPointerStringScanPlan) SetNext(next ScanPlan) { plan.next = next }
   829  
   830  func (plan *wrapMapStringToPointerStringScanPlan) Scan(src []byte, dst any) error {
   831  	return plan.next.Scan(src, (*mapStringToPointerStringWrapper)(dst.(*map[string]*string)))
   832  }
   833  
   834  type wrapMapStringToStringScanPlan struct {
   835  	next ScanPlan
   836  }
   837  
   838  func (plan *wrapMapStringToStringScanPlan) SetNext(next ScanPlan) { plan.next = next }
   839  
   840  func (plan *wrapMapStringToStringScanPlan) Scan(src []byte, dst any) error {
   841  	return plan.next.Scan(src, (*mapStringToStringWrapper)(dst.(*map[string]string)))
   842  }
   843  
   844  type wrapByte16ScanPlan struct {
   845  	next ScanPlan
   846  }
   847  
   848  func (plan *wrapByte16ScanPlan) SetNext(next ScanPlan) { plan.next = next }
   849  
   850  func (plan *wrapByte16ScanPlan) Scan(src []byte, dst any) error {
   851  	return plan.next.Scan(src, (*byte16Wrapper)(dst.(*[16]byte)))
   852  }
   853  
   854  type wrapByteSliceScanPlan struct {
   855  	next ScanPlan
   856  }
   857  
   858  func (plan *wrapByteSliceScanPlan) SetNext(next ScanPlan) { plan.next = next }
   859  
   860  func (plan *wrapByteSliceScanPlan) Scan(src []byte, dst any) error {
   861  	return plan.next.Scan(src, (*byteSliceWrapper)(dst.(*[]byte)))
   862  }
   863  
   864  type pointerEmptyInterfaceScanPlan struct {
   865  	codec      Codec
   866  	m          *Map
   867  	oid        uint32
   868  	formatCode int16
   869  }
   870  
   871  func (plan *pointerEmptyInterfaceScanPlan) Scan(src []byte, dst any) error {
   872  	value, err := plan.codec.DecodeValue(plan.m, plan.oid, plan.formatCode, src)
   873  	if err != nil {
   874  		return err
   875  	}
   876  
   877  	ptrAny := dst.(*any)
   878  	*ptrAny = value
   879  
   880  	return nil
   881  }
   882  
   883  // TryWrapStructPlan tries to wrap a struct with a wrapper that implements CompositeIndexGetter.
   884  func TryWrapStructScanPlan(target any) (plan WrappedScanPlanNextSetter, nextValue any, ok bool) {
   885  	targetValue := reflect.ValueOf(target)
   886  	if targetValue.Kind() != reflect.Ptr {
   887  		return nil, nil, false
   888  	}
   889  
   890  	var targetElemValue reflect.Value
   891  	if targetValue.IsNil() {
   892  		targetElemValue = reflect.Zero(targetValue.Type().Elem())
   893  	} else {
   894  		targetElemValue = targetValue.Elem()
   895  	}
   896  	targetElemType := targetElemValue.Type()
   897  
   898  	if targetElemType.Kind() == reflect.Struct {
   899  		exportedFields := getExportedFieldValues(targetElemValue)
   900  		if len(exportedFields) == 0 {
   901  			return nil, nil, false
   902  		}
   903  
   904  		w := ptrStructWrapper{
   905  			s:              target,
   906  			exportedFields: exportedFields,
   907  		}
   908  		return &wrapAnyPtrStructScanPlan{}, &w, true
   909  	}
   910  
   911  	return nil, nil, false
   912  }
   913  
   914  type wrapAnyPtrStructScanPlan struct {
   915  	next ScanPlan
   916  }
   917  
   918  func (plan *wrapAnyPtrStructScanPlan) SetNext(next ScanPlan) { plan.next = next }
   919  
   920  func (plan *wrapAnyPtrStructScanPlan) Scan(src []byte, target any) error {
   921  	w := ptrStructWrapper{
   922  		s:              target,
   923  		exportedFields: getExportedFieldValues(reflect.ValueOf(target).Elem()),
   924  	}
   925  
   926  	return plan.next.Scan(src, &w)
   927  }
   928  
   929  // TryWrapPtrSliceScanPlan tries to wrap a pointer to a single dimension slice.
   930  func TryWrapPtrSliceScanPlan(target any) (plan WrappedScanPlanNextSetter, nextValue any, ok bool) {
   931  	// Avoid using reflect path for common types.
   932  	switch target := target.(type) {
   933  	case *[]int16:
   934  		return &wrapPtrSliceScanPlan[int16]{}, (*FlatArray[int16])(target), true
   935  	case *[]int32:
   936  		return &wrapPtrSliceScanPlan[int32]{}, (*FlatArray[int32])(target), true
   937  	case *[]int64:
   938  		return &wrapPtrSliceScanPlan[int64]{}, (*FlatArray[int64])(target), true
   939  	case *[]float32:
   940  		return &wrapPtrSliceScanPlan[float32]{}, (*FlatArray[float32])(target), true
   941  	case *[]float64:
   942  		return &wrapPtrSliceScanPlan[float64]{}, (*FlatArray[float64])(target), true
   943  	case *[]string:
   944  		return &wrapPtrSliceScanPlan[string]{}, (*FlatArray[string])(target), true
   945  	case *[]time.Time:
   946  		return &wrapPtrSliceScanPlan[time.Time]{}, (*FlatArray[time.Time])(target), true
   947  	}
   948  
   949  	targetType := reflect.TypeOf(target)
   950  	if targetType.Kind() != reflect.Ptr {
   951  		return nil, nil, false
   952  	}
   953  
   954  	targetElemType := targetType.Elem()
   955  
   956  	if targetElemType.Kind() == reflect.Slice {
   957  		slice := reflect.New(targetElemType).Elem()
   958  		return &wrapPtrSliceReflectScanPlan{}, &anySliceArrayReflect{slice: slice}, true
   959  	}
   960  	return nil, nil, false
   961  }
   962  
   963  type wrapPtrSliceScanPlan[T any] struct {
   964  	next ScanPlan
   965  }
   966  
   967  func (plan *wrapPtrSliceScanPlan[T]) SetNext(next ScanPlan) { plan.next = next }
   968  
   969  func (plan *wrapPtrSliceScanPlan[T]) Scan(src []byte, target any) error {
   970  	return plan.next.Scan(src, (*FlatArray[T])(target.(*[]T)))
   971  }
   972  
   973  type wrapPtrSliceReflectScanPlan struct {
   974  	next ScanPlan
   975  }
   976  
   977  func (plan *wrapPtrSliceReflectScanPlan) SetNext(next ScanPlan) { plan.next = next }
   978  
   979  func (plan *wrapPtrSliceReflectScanPlan) Scan(src []byte, target any) error {
   980  	return plan.next.Scan(src, &anySliceArrayReflect{slice: reflect.ValueOf(target).Elem()})
   981  }
   982  
   983  // TryWrapPtrMultiDimSliceScanPlan tries to wrap a pointer to a multi-dimension slice.
   984  func TryWrapPtrMultiDimSliceScanPlan(target any) (plan WrappedScanPlanNextSetter, nextValue any, ok bool) {
   985  	targetValue := reflect.ValueOf(target)
   986  	if targetValue.Kind() != reflect.Ptr {
   987  		return nil, nil, false
   988  	}
   989  
   990  	targetElemValue := targetValue.Elem()
   991  
   992  	if targetElemValue.Kind() == reflect.Slice {
   993  		elemElemKind := targetElemValue.Type().Elem().Kind()
   994  		if elemElemKind == reflect.Slice {
   995  			if !isRagged(targetElemValue) {
   996  				return &wrapPtrMultiDimSliceScanPlan{}, &anyMultiDimSliceArray{slice: targetValue.Elem()}, true
   997  			}
   998  		}
   999  	}
  1000  
  1001  	return nil, nil, false
  1002  }
  1003  
  1004  type wrapPtrMultiDimSliceScanPlan struct {
  1005  	next ScanPlan
  1006  }
  1007  
  1008  func (plan *wrapPtrMultiDimSliceScanPlan) SetNext(next ScanPlan) { plan.next = next }
  1009  
  1010  func (plan *wrapPtrMultiDimSliceScanPlan) Scan(src []byte, target any) error {
  1011  	return plan.next.Scan(src, &anyMultiDimSliceArray{slice: reflect.ValueOf(target).Elem()})
  1012  }
  1013  
  1014  // TryWrapPtrArrayScanPlan tries to wrap a pointer to a single dimension array.
  1015  func TryWrapPtrArrayScanPlan(target any) (plan WrappedScanPlanNextSetter, nextValue any, ok bool) {
  1016  	targetValue := reflect.ValueOf(target)
  1017  	if targetValue.Kind() != reflect.Ptr {
  1018  		return nil, nil, false
  1019  	}
  1020  
  1021  	targetElemValue := targetValue.Elem()
  1022  
  1023  	if targetElemValue.Kind() == reflect.Array {
  1024  		return &wrapPtrArrayReflectScanPlan{}, &anyArrayArrayReflect{array: targetElemValue}, true
  1025  	}
  1026  	return nil, nil, false
  1027  }
  1028  
  1029  type wrapPtrArrayReflectScanPlan struct {
  1030  	next ScanPlan
  1031  }
  1032  
  1033  func (plan *wrapPtrArrayReflectScanPlan) SetNext(next ScanPlan) { plan.next = next }
  1034  
  1035  func (plan *wrapPtrArrayReflectScanPlan) Scan(src []byte, target any) error {
  1036  	return plan.next.Scan(src, &anyArrayArrayReflect{array: reflect.ValueOf(target).Elem()})
  1037  }
  1038  
  1039  // PlanScan prepares a plan to scan a value into target.
  1040  func (m *Map) PlanScan(oid uint32, formatCode int16, target any) ScanPlan {
  1041  	oidMemo := m.memoizedScanPlans[oid]
  1042  	if oidMemo == nil {
  1043  		oidMemo = make(map[reflect.Type][2]ScanPlan)
  1044  		m.memoizedScanPlans[oid] = oidMemo
  1045  	}
  1046  	targetReflectType := reflect.TypeOf(target)
  1047  	typeMemo := oidMemo[targetReflectType]
  1048  	plan := typeMemo[formatCode]
  1049  	if plan == nil {
  1050  		plan = m.planScan(oid, formatCode, target)
  1051  		typeMemo[formatCode] = plan
  1052  		oidMemo[targetReflectType] = typeMemo
  1053  	}
  1054  
  1055  	return plan
  1056  }
  1057  
  1058  func (m *Map) planScan(oid uint32, formatCode int16, target any) ScanPlan {
  1059  	if target == nil {
  1060  		return &scanPlanFail{m: m, oid: oid, formatCode: formatCode}
  1061  	}
  1062  
  1063  	if _, ok := target.(*UndecodedBytes); ok {
  1064  		return scanPlanAnyToUndecodedBytes{}
  1065  	}
  1066  
  1067  	switch formatCode {
  1068  	case BinaryFormatCode:
  1069  		switch target.(type) {
  1070  		case *string:
  1071  			switch oid {
  1072  			case TextOID, VarcharOID:
  1073  				return scanPlanString{}
  1074  			}
  1075  		}
  1076  	case TextFormatCode:
  1077  		switch target.(type) {
  1078  		case *string:
  1079  			return scanPlanString{}
  1080  		case *[]byte:
  1081  			if oid != ByteaOID {
  1082  				return scanPlanAnyTextToBytes{}
  1083  			}
  1084  		case TextScanner:
  1085  			return scanPlanTextAnyToTextScanner{}
  1086  		}
  1087  	}
  1088  
  1089  	var dt *Type
  1090  
  1091  	if dataType, ok := m.TypeForOID(oid); ok {
  1092  		dt = dataType
  1093  	} else if dataType, ok := m.TypeForValue(target); ok {
  1094  		dt = dataType
  1095  		oid = dt.OID // Preserve assumed OID in case we are recursively called below.
  1096  	}
  1097  
  1098  	if dt != nil {
  1099  		if plan := dt.Codec.PlanScan(m, oid, formatCode, target); plan != nil {
  1100  			return plan
  1101  		}
  1102  	}
  1103  
  1104  	// This needs to happen before trying m.TryWrapScanPlanFuncs. Otherwise, a sql.Scanner would not get called if it was
  1105  	// defined on a type that could be unwrapped such as `type myString string`.
  1106  	//
  1107  	//  https://github.com/jackc/pgtype/issues/197
  1108  	if _, ok := target.(sql.Scanner); ok {
  1109  		if dt == nil {
  1110  			return &scanPlanSQLScanner{formatCode: formatCode}
  1111  		} else {
  1112  			return &scanPlanCodecSQLScanner{c: dt.Codec, m: m, oid: oid, formatCode: formatCode}
  1113  		}
  1114  	}
  1115  
  1116  	for _, f := range m.TryWrapScanPlanFuncs {
  1117  		if wrapperPlan, nextDst, ok := f(target); ok {
  1118  			if nextPlan := m.planScan(oid, formatCode, nextDst); nextPlan != nil {
  1119  				if _, failed := nextPlan.(*scanPlanFail); !failed {
  1120  					wrapperPlan.SetNext(nextPlan)
  1121  					return wrapperPlan
  1122  				}
  1123  			}
  1124  		}
  1125  	}
  1126  
  1127  	if dt != nil {
  1128  		if _, ok := target.(*any); ok {
  1129  			return &pointerEmptyInterfaceScanPlan{codec: dt.Codec, m: m, oid: oid, formatCode: formatCode}
  1130  		}
  1131  	}
  1132  
  1133  	return &scanPlanFail{m: m, oid: oid, formatCode: formatCode}
  1134  }
  1135  
  1136  func (m *Map) Scan(oid uint32, formatCode int16, src []byte, dst any) error {
  1137  	if dst == nil {
  1138  		return nil
  1139  	}
  1140  
  1141  	plan := m.PlanScan(oid, formatCode, dst)
  1142  	return plan.Scan(src, dst)
  1143  }
  1144  
  1145  var ErrScanTargetTypeChanged = errors.New("scan target type changed")
  1146  
  1147  func codecScan(codec Codec, m *Map, oid uint32, format int16, src []byte, dst any) error {
  1148  	scanPlan := codec.PlanScan(m, oid, format, dst)
  1149  	if scanPlan == nil {
  1150  		return fmt.Errorf("PlanScan did not find a plan")
  1151  	}
  1152  	return scanPlan.Scan(src, dst)
  1153  }
  1154  
  1155  func codecDecodeToTextFormat(codec Codec, m *Map, oid uint32, format int16, src []byte) (driver.Value, error) {
  1156  	if src == nil {
  1157  		return nil, nil
  1158  	}
  1159  
  1160  	if format == TextFormatCode {
  1161  		return string(src), nil
  1162  	} else {
  1163  		value, err := codec.DecodeValue(m, oid, format, src)
  1164  		if err != nil {
  1165  			return nil, err
  1166  		}
  1167  		buf, err := m.Encode(oid, TextFormatCode, value, nil)
  1168  		if err != nil {
  1169  			return nil, err
  1170  		}
  1171  		return string(buf), nil
  1172  	}
  1173  }
  1174  
  1175  // PlanEncode returns an Encode plan for encoding value into PostgreSQL format for oid and format. If no plan can be
  1176  // found then nil is returned.
  1177  func (m *Map) PlanEncode(oid uint32, format int16, value any) EncodePlan {
  1178  	oidMemo := m.memoizedEncodePlans[oid]
  1179  	if oidMemo == nil {
  1180  		oidMemo = make(map[reflect.Type][2]EncodePlan)
  1181  		m.memoizedEncodePlans[oid] = oidMemo
  1182  	}
  1183  	targetReflectType := reflect.TypeOf(value)
  1184  	typeMemo := oidMemo[targetReflectType]
  1185  	plan := typeMemo[format]
  1186  	if plan == nil {
  1187  		plan = m.planEncode(oid, format, value)
  1188  		typeMemo[format] = plan
  1189  		oidMemo[targetReflectType] = typeMemo
  1190  	}
  1191  
  1192  	return plan
  1193  }
  1194  
  1195  func (m *Map) planEncode(oid uint32, format int16, value any) EncodePlan {
  1196  	if format == TextFormatCode {
  1197  		switch value.(type) {
  1198  		case string:
  1199  			return encodePlanStringToAnyTextFormat{}
  1200  		case TextValuer:
  1201  			return encodePlanTextValuerToAnyTextFormat{}
  1202  		}
  1203  	}
  1204  
  1205  	var dt *Type
  1206  	if dataType, ok := m.TypeForOID(oid); ok {
  1207  		dt = dataType
  1208  	} else {
  1209  		// If no type for the OID was found, then either it is unknowable (e.g. the simple protocol) or it is an
  1210  		// unregistered type. In either case try to find the type and OID that matches the value (e.g. a []byte would be
  1211  		// registered to PostgreSQL bytea).
  1212  		if dataType, ok := m.TypeForValue(value); ok {
  1213  			dt = dataType
  1214  			oid = dt.OID // Preserve assumed OID in case we are recursively called below.
  1215  		}
  1216  	}
  1217  
  1218  	if dt != nil {
  1219  		if plan := dt.Codec.PlanEncode(m, oid, format, value); plan != nil {
  1220  			return plan
  1221  		}
  1222  	}
  1223  
  1224  	for _, f := range m.TryWrapEncodePlanFuncs {
  1225  		if wrapperPlan, nextValue, ok := f(value); ok {
  1226  			if nextPlan := m.PlanEncode(oid, format, nextValue); nextPlan != nil {
  1227  				wrapperPlan.SetNext(nextPlan)
  1228  				return wrapperPlan
  1229  			}
  1230  		}
  1231  	}
  1232  
  1233  	if _, ok := value.(driver.Valuer); ok {
  1234  		return &encodePlanDriverValuer{m: m, oid: oid, formatCode: format}
  1235  	}
  1236  
  1237  	return nil
  1238  }
  1239  
  1240  type encodePlanStringToAnyTextFormat struct{}
  1241  
  1242  func (encodePlanStringToAnyTextFormat) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1243  	s := value.(string)
  1244  	return append(buf, s...), nil
  1245  }
  1246  
  1247  type encodePlanTextValuerToAnyTextFormat struct{}
  1248  
  1249  func (encodePlanTextValuerToAnyTextFormat) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1250  	t, err := value.(TextValuer).TextValue()
  1251  	if err != nil {
  1252  		return nil, err
  1253  	}
  1254  	if !t.Valid {
  1255  		return nil, nil
  1256  	}
  1257  
  1258  	return append(buf, t.String...), nil
  1259  }
  1260  
  1261  type encodePlanDriverValuer struct {
  1262  	m          *Map
  1263  	oid        uint32
  1264  	formatCode int16
  1265  }
  1266  
  1267  func (plan *encodePlanDriverValuer) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1268  	dv := value.(driver.Valuer)
  1269  	if dv == nil {
  1270  		return nil, nil
  1271  	}
  1272  	v, err := dv.Value()
  1273  	if err != nil {
  1274  		return nil, err
  1275  	}
  1276  	if v == nil {
  1277  		return nil, nil
  1278  	}
  1279  
  1280  	newBuf, err = plan.m.Encode(plan.oid, plan.formatCode, v, buf)
  1281  	if err == nil {
  1282  		return newBuf, nil
  1283  	}
  1284  
  1285  	s, ok := v.(string)
  1286  	if !ok {
  1287  		return nil, err
  1288  	}
  1289  
  1290  	var scannedValue any
  1291  	scanErr := plan.m.Scan(plan.oid, TextFormatCode, []byte(s), &scannedValue)
  1292  	if scanErr != nil {
  1293  		return nil, err
  1294  	}
  1295  
  1296  	// Prevent infinite loop. We can't encode this. See https://github.com/jackc/pgx/issues/1331.
  1297  	if reflect.TypeOf(value) == reflect.TypeOf(scannedValue) {
  1298  		return nil, fmt.Errorf("tried to encode %v via encoding to text and scanning but failed due to receiving same type back", value)
  1299  	}
  1300  
  1301  	var err2 error
  1302  	newBuf, err2 = plan.m.Encode(plan.oid, BinaryFormatCode, scannedValue, buf)
  1303  	if err2 != nil {
  1304  		return nil, err
  1305  	}
  1306  
  1307  	return newBuf, nil
  1308  }
  1309  
  1310  // TryWrapEncodePlanFunc is a function that tries to create a wrapper plan for value. If successful it returns a plan
  1311  // that will convert the value passed to Encode and then call the next plan. nextValue is value as it will be converted
  1312  // by plan. It must be used to find another suitable EncodePlan. When it is found SetNext must be called on plan for it
  1313  // to be usabled. ok indicates if a suitable wrapper was found.
  1314  type TryWrapEncodePlanFunc func(value any) (plan WrappedEncodePlanNextSetter, nextValue any, ok bool)
  1315  
  1316  type derefPointerEncodePlan struct {
  1317  	next EncodePlan
  1318  }
  1319  
  1320  func (plan *derefPointerEncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1321  
  1322  func (plan *derefPointerEncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1323  	ptr := reflect.ValueOf(value)
  1324  
  1325  	if ptr.IsNil() {
  1326  		return nil, nil
  1327  	}
  1328  
  1329  	return plan.next.Encode(ptr.Elem().Interface(), buf)
  1330  }
  1331  
  1332  // TryWrapDerefPointerEncodePlan tries to dereference a pointer. e.g. If value was of type *string then a wrapper plan
  1333  // would be returned that derefences the value.
  1334  func TryWrapDerefPointerEncodePlan(value any) (plan WrappedEncodePlanNextSetter, nextValue any, ok bool) {
  1335  	if _, ok := value.(driver.Valuer); ok {
  1336  		return nil, nil, false
  1337  	}
  1338  
  1339  	if valueType := reflect.TypeOf(value); valueType != nil && valueType.Kind() == reflect.Ptr {
  1340  		return &derefPointerEncodePlan{}, reflect.New(valueType.Elem()).Elem().Interface(), true
  1341  	}
  1342  
  1343  	return nil, nil, false
  1344  }
  1345  
  1346  var kindToTypes map[reflect.Kind]reflect.Type = map[reflect.Kind]reflect.Type{
  1347  	reflect.Int:     reflect.TypeOf(int(0)),
  1348  	reflect.Int8:    reflect.TypeOf(int8(0)),
  1349  	reflect.Int16:   reflect.TypeOf(int16(0)),
  1350  	reflect.Int32:   reflect.TypeOf(int32(0)),
  1351  	reflect.Int64:   reflect.TypeOf(int64(0)),
  1352  	reflect.Uint:    reflect.TypeOf(uint(0)),
  1353  	reflect.Uint8:   reflect.TypeOf(uint8(0)),
  1354  	reflect.Uint16:  reflect.TypeOf(uint16(0)),
  1355  	reflect.Uint32:  reflect.TypeOf(uint32(0)),
  1356  	reflect.Uint64:  reflect.TypeOf(uint64(0)),
  1357  	reflect.Float32: reflect.TypeOf(float32(0)),
  1358  	reflect.Float64: reflect.TypeOf(float64(0)),
  1359  	reflect.String:  reflect.TypeOf(""),
  1360  	reflect.Bool:    reflect.TypeOf(false),
  1361  }
  1362  
  1363  var byteSliceType = reflect.TypeOf([]byte{})
  1364  
  1365  type underlyingTypeEncodePlan struct {
  1366  	nextValueType reflect.Type
  1367  	next          EncodePlan
  1368  }
  1369  
  1370  func (plan *underlyingTypeEncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1371  
  1372  func (plan *underlyingTypeEncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1373  	return plan.next.Encode(reflect.ValueOf(value).Convert(plan.nextValueType).Interface(), buf)
  1374  }
  1375  
  1376  // TryWrapFindUnderlyingTypeEncodePlan tries to convert to a Go builtin type. e.g. If value was of type MyString and
  1377  // MyString was defined as a string then a wrapper plan would be returned that converts MyString to string.
  1378  func TryWrapFindUnderlyingTypeEncodePlan(value any) (plan WrappedEncodePlanNextSetter, nextValue any, ok bool) {
  1379  	if value == nil {
  1380  		return nil, nil, false
  1381  	}
  1382  
  1383  	if _, ok := value.(driver.Valuer); ok {
  1384  		return nil, nil, false
  1385  	}
  1386  
  1387  	if _, ok := value.(SkipUnderlyingTypePlanner); ok {
  1388  		return nil, nil, false
  1389  	}
  1390  
  1391  	refValue := reflect.ValueOf(value)
  1392  
  1393  	nextValueType := kindToTypes[refValue.Kind()]
  1394  	if nextValueType != nil && refValue.Type() != nextValueType {
  1395  		return &underlyingTypeEncodePlan{nextValueType: nextValueType}, refValue.Convert(nextValueType).Interface(), true
  1396  	}
  1397  
  1398  	// []byte is a special case. It is a slice but we treat it as a scalar type. In the case of a named type like
  1399  	// json.RawMessage which is defined as []byte the underlying type should be considered as []byte. But any other slice
  1400  	// does not have a special underlying type.
  1401  	//
  1402  	// https://github.com/jackc/pgx/issues/1763
  1403  	if refValue.Type() != byteSliceType && refValue.Type().AssignableTo(byteSliceType) {
  1404  		return &underlyingTypeEncodePlan{nextValueType: byteSliceType}, refValue.Convert(byteSliceType).Interface(), true
  1405  	}
  1406  
  1407  	return nil, nil, false
  1408  }
  1409  
  1410  type WrappedEncodePlanNextSetter interface {
  1411  	SetNext(EncodePlan)
  1412  	EncodePlan
  1413  }
  1414  
  1415  // TryWrapBuiltinTypeEncodePlan tries to wrap a builtin type with a wrapper that provides additional methods. e.g. If
  1416  // value was of type int32 then a wrapper plan would be returned that converts value to a type that implements
  1417  // Int64Valuer.
  1418  func TryWrapBuiltinTypeEncodePlan(value any) (plan WrappedEncodePlanNextSetter, nextValue any, ok bool) {
  1419  	if _, ok := value.(driver.Valuer); ok {
  1420  		return nil, nil, false
  1421  	}
  1422  
  1423  	switch value := value.(type) {
  1424  	case int8:
  1425  		return &wrapInt8EncodePlan{}, int8Wrapper(value), true
  1426  	case int16:
  1427  		return &wrapInt16EncodePlan{}, int16Wrapper(value), true
  1428  	case int32:
  1429  		return &wrapInt32EncodePlan{}, int32Wrapper(value), true
  1430  	case int64:
  1431  		return &wrapInt64EncodePlan{}, int64Wrapper(value), true
  1432  	case int:
  1433  		return &wrapIntEncodePlan{}, intWrapper(value), true
  1434  	case uint8:
  1435  		return &wrapUint8EncodePlan{}, uint8Wrapper(value), true
  1436  	case uint16:
  1437  		return &wrapUint16EncodePlan{}, uint16Wrapper(value), true
  1438  	case uint32:
  1439  		return &wrapUint32EncodePlan{}, uint32Wrapper(value), true
  1440  	case uint64:
  1441  		return &wrapUint64EncodePlan{}, uint64Wrapper(value), true
  1442  	case uint:
  1443  		return &wrapUintEncodePlan{}, uintWrapper(value), true
  1444  	case float32:
  1445  		return &wrapFloat32EncodePlan{}, float32Wrapper(value), true
  1446  	case float64:
  1447  		return &wrapFloat64EncodePlan{}, float64Wrapper(value), true
  1448  	case string:
  1449  		return &wrapStringEncodePlan{}, stringWrapper(value), true
  1450  	case time.Time:
  1451  		return &wrapTimeEncodePlan{}, timeWrapper(value), true
  1452  	case time.Duration:
  1453  		return &wrapDurationEncodePlan{}, durationWrapper(value), true
  1454  	case net.IPNet:
  1455  		return &wrapNetIPNetEncodePlan{}, netIPNetWrapper(value), true
  1456  	case net.IP:
  1457  		return &wrapNetIPEncodePlan{}, netIPWrapper(value), true
  1458  	case netip.Prefix:
  1459  		return &wrapNetipPrefixEncodePlan{}, netipPrefixWrapper(value), true
  1460  	case netip.Addr:
  1461  		return &wrapNetipAddrEncodePlan{}, netipAddrWrapper(value), true
  1462  	case map[string]*string:
  1463  		return &wrapMapStringToPointerStringEncodePlan{}, mapStringToPointerStringWrapper(value), true
  1464  	case map[string]string:
  1465  		return &wrapMapStringToStringEncodePlan{}, mapStringToStringWrapper(value), true
  1466  	case [16]byte:
  1467  		return &wrapByte16EncodePlan{}, byte16Wrapper(value), true
  1468  	case []byte:
  1469  		return &wrapByteSliceEncodePlan{}, byteSliceWrapper(value), true
  1470  	case fmt.Stringer:
  1471  		return &wrapFmtStringerEncodePlan{}, fmtStringerWrapper{value}, true
  1472  	}
  1473  
  1474  	return nil, nil, false
  1475  }
  1476  
  1477  type wrapInt8EncodePlan struct {
  1478  	next EncodePlan
  1479  }
  1480  
  1481  func (plan *wrapInt8EncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1482  
  1483  func (plan *wrapInt8EncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1484  	return plan.next.Encode(int8Wrapper(value.(int8)), buf)
  1485  }
  1486  
  1487  type wrapInt16EncodePlan struct {
  1488  	next EncodePlan
  1489  }
  1490  
  1491  func (plan *wrapInt16EncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1492  
  1493  func (plan *wrapInt16EncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1494  	return plan.next.Encode(int16Wrapper(value.(int16)), buf)
  1495  }
  1496  
  1497  type wrapInt32EncodePlan struct {
  1498  	next EncodePlan
  1499  }
  1500  
  1501  func (plan *wrapInt32EncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1502  
  1503  func (plan *wrapInt32EncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1504  	return plan.next.Encode(int32Wrapper(value.(int32)), buf)
  1505  }
  1506  
  1507  type wrapInt64EncodePlan struct {
  1508  	next EncodePlan
  1509  }
  1510  
  1511  func (plan *wrapInt64EncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1512  
  1513  func (plan *wrapInt64EncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1514  	return plan.next.Encode(int64Wrapper(value.(int64)), buf)
  1515  }
  1516  
  1517  type wrapIntEncodePlan struct {
  1518  	next EncodePlan
  1519  }
  1520  
  1521  func (plan *wrapIntEncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1522  
  1523  func (plan *wrapIntEncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1524  	return plan.next.Encode(intWrapper(value.(int)), buf)
  1525  }
  1526  
  1527  type wrapUint8EncodePlan struct {
  1528  	next EncodePlan
  1529  }
  1530  
  1531  func (plan *wrapUint8EncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1532  
  1533  func (plan *wrapUint8EncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1534  	return plan.next.Encode(uint8Wrapper(value.(uint8)), buf)
  1535  }
  1536  
  1537  type wrapUint16EncodePlan struct {
  1538  	next EncodePlan
  1539  }
  1540  
  1541  func (plan *wrapUint16EncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1542  
  1543  func (plan *wrapUint16EncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1544  	return plan.next.Encode(uint16Wrapper(value.(uint16)), buf)
  1545  }
  1546  
  1547  type wrapUint32EncodePlan struct {
  1548  	next EncodePlan
  1549  }
  1550  
  1551  func (plan *wrapUint32EncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1552  
  1553  func (plan *wrapUint32EncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1554  	return plan.next.Encode(uint32Wrapper(value.(uint32)), buf)
  1555  }
  1556  
  1557  type wrapUint64EncodePlan struct {
  1558  	next EncodePlan
  1559  }
  1560  
  1561  func (plan *wrapUint64EncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1562  
  1563  func (plan *wrapUint64EncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1564  	return plan.next.Encode(uint64Wrapper(value.(uint64)), buf)
  1565  }
  1566  
  1567  type wrapUintEncodePlan struct {
  1568  	next EncodePlan
  1569  }
  1570  
  1571  func (plan *wrapUintEncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1572  
  1573  func (plan *wrapUintEncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1574  	return plan.next.Encode(uintWrapper(value.(uint)), buf)
  1575  }
  1576  
  1577  type wrapFloat32EncodePlan struct {
  1578  	next EncodePlan
  1579  }
  1580  
  1581  func (plan *wrapFloat32EncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1582  
  1583  func (plan *wrapFloat32EncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1584  	return plan.next.Encode(float32Wrapper(value.(float32)), buf)
  1585  }
  1586  
  1587  type wrapFloat64EncodePlan struct {
  1588  	next EncodePlan
  1589  }
  1590  
  1591  func (plan *wrapFloat64EncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1592  
  1593  func (plan *wrapFloat64EncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1594  	return plan.next.Encode(float64Wrapper(value.(float64)), buf)
  1595  }
  1596  
  1597  type wrapStringEncodePlan struct {
  1598  	next EncodePlan
  1599  }
  1600  
  1601  func (plan *wrapStringEncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1602  
  1603  func (plan *wrapStringEncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1604  	return plan.next.Encode(stringWrapper(value.(string)), buf)
  1605  }
  1606  
  1607  type wrapTimeEncodePlan struct {
  1608  	next EncodePlan
  1609  }
  1610  
  1611  func (plan *wrapTimeEncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1612  
  1613  func (plan *wrapTimeEncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1614  	return plan.next.Encode(timeWrapper(value.(time.Time)), buf)
  1615  }
  1616  
  1617  type wrapDurationEncodePlan struct {
  1618  	next EncodePlan
  1619  }
  1620  
  1621  func (plan *wrapDurationEncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1622  
  1623  func (plan *wrapDurationEncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1624  	return plan.next.Encode(durationWrapper(value.(time.Duration)), buf)
  1625  }
  1626  
  1627  type wrapNetIPNetEncodePlan struct {
  1628  	next EncodePlan
  1629  }
  1630  
  1631  func (plan *wrapNetIPNetEncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1632  
  1633  func (plan *wrapNetIPNetEncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1634  	return plan.next.Encode(netIPNetWrapper(value.(net.IPNet)), buf)
  1635  }
  1636  
  1637  type wrapNetIPEncodePlan struct {
  1638  	next EncodePlan
  1639  }
  1640  
  1641  func (plan *wrapNetIPEncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1642  
  1643  func (plan *wrapNetIPEncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1644  	return plan.next.Encode(netIPWrapper(value.(net.IP)), buf)
  1645  }
  1646  
  1647  type wrapNetipPrefixEncodePlan struct {
  1648  	next EncodePlan
  1649  }
  1650  
  1651  func (plan *wrapNetipPrefixEncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1652  
  1653  func (plan *wrapNetipPrefixEncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1654  	return plan.next.Encode(netipPrefixWrapper(value.(netip.Prefix)), buf)
  1655  }
  1656  
  1657  type wrapNetipAddrEncodePlan struct {
  1658  	next EncodePlan
  1659  }
  1660  
  1661  func (plan *wrapNetipAddrEncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1662  
  1663  func (plan *wrapNetipAddrEncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1664  	return plan.next.Encode(netipAddrWrapper(value.(netip.Addr)), buf)
  1665  }
  1666  
  1667  type wrapMapStringToPointerStringEncodePlan struct {
  1668  	next EncodePlan
  1669  }
  1670  
  1671  func (plan *wrapMapStringToPointerStringEncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1672  
  1673  func (plan *wrapMapStringToPointerStringEncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1674  	return plan.next.Encode(mapStringToPointerStringWrapper(value.(map[string]*string)), buf)
  1675  }
  1676  
  1677  type wrapMapStringToStringEncodePlan struct {
  1678  	next EncodePlan
  1679  }
  1680  
  1681  func (plan *wrapMapStringToStringEncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1682  
  1683  func (plan *wrapMapStringToStringEncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1684  	return plan.next.Encode(mapStringToStringWrapper(value.(map[string]string)), buf)
  1685  }
  1686  
  1687  type wrapByte16EncodePlan struct {
  1688  	next EncodePlan
  1689  }
  1690  
  1691  func (plan *wrapByte16EncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1692  
  1693  func (plan *wrapByte16EncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1694  	return plan.next.Encode(byte16Wrapper(value.([16]byte)), buf)
  1695  }
  1696  
  1697  type wrapByteSliceEncodePlan struct {
  1698  	next EncodePlan
  1699  }
  1700  
  1701  func (plan *wrapByteSliceEncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1702  
  1703  func (plan *wrapByteSliceEncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1704  	return plan.next.Encode(byteSliceWrapper(value.([]byte)), buf)
  1705  }
  1706  
  1707  type wrapFmtStringerEncodePlan struct {
  1708  	next EncodePlan
  1709  }
  1710  
  1711  func (plan *wrapFmtStringerEncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1712  
  1713  func (plan *wrapFmtStringerEncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1714  	return plan.next.Encode(fmtStringerWrapper{value.(fmt.Stringer)}, buf)
  1715  }
  1716  
  1717  // TryWrapStructPlan tries to wrap a struct with a wrapper that implements CompositeIndexGetter.
  1718  func TryWrapStructEncodePlan(value any) (plan WrappedEncodePlanNextSetter, nextValue any, ok bool) {
  1719  	if _, ok := value.(driver.Valuer); ok {
  1720  		return nil, nil, false
  1721  	}
  1722  
  1723  	if valueType := reflect.TypeOf(value); valueType != nil && valueType.Kind() == reflect.Struct {
  1724  		exportedFields := getExportedFieldValues(reflect.ValueOf(value))
  1725  		if len(exportedFields) == 0 {
  1726  			return nil, nil, false
  1727  		}
  1728  
  1729  		w := structWrapper{
  1730  			s:              value,
  1731  			exportedFields: exportedFields,
  1732  		}
  1733  		return &wrapAnyStructEncodePlan{}, w, true
  1734  	}
  1735  
  1736  	return nil, nil, false
  1737  }
  1738  
  1739  type wrapAnyStructEncodePlan struct {
  1740  	next EncodePlan
  1741  }
  1742  
  1743  func (plan *wrapAnyStructEncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1744  
  1745  func (plan *wrapAnyStructEncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1746  	w := structWrapper{
  1747  		s:              value,
  1748  		exportedFields: getExportedFieldValues(reflect.ValueOf(value)),
  1749  	}
  1750  
  1751  	return plan.next.Encode(w, buf)
  1752  }
  1753  
  1754  func getExportedFieldValues(structValue reflect.Value) []reflect.Value {
  1755  	structType := structValue.Type()
  1756  	exportedFields := make([]reflect.Value, 0, structValue.NumField())
  1757  	for i := 0; i < structType.NumField(); i++ {
  1758  		sf := structType.Field(i)
  1759  		if sf.IsExported() {
  1760  			exportedFields = append(exportedFields, structValue.Field(i))
  1761  		}
  1762  	}
  1763  
  1764  	return exportedFields
  1765  }
  1766  
  1767  func TryWrapSliceEncodePlan(value any) (plan WrappedEncodePlanNextSetter, nextValue any, ok bool) {
  1768  	if _, ok := value.(driver.Valuer); ok {
  1769  		return nil, nil, false
  1770  	}
  1771  
  1772  	// Avoid using reflect path for common types.
  1773  	switch value := value.(type) {
  1774  	case []int16:
  1775  		return &wrapSliceEncodePlan[int16]{}, (FlatArray[int16])(value), true
  1776  	case []int32:
  1777  		return &wrapSliceEncodePlan[int32]{}, (FlatArray[int32])(value), true
  1778  	case []int64:
  1779  		return &wrapSliceEncodePlan[int64]{}, (FlatArray[int64])(value), true
  1780  	case []float32:
  1781  		return &wrapSliceEncodePlan[float32]{}, (FlatArray[float32])(value), true
  1782  	case []float64:
  1783  		return &wrapSliceEncodePlan[float64]{}, (FlatArray[float64])(value), true
  1784  	case []string:
  1785  		return &wrapSliceEncodePlan[string]{}, (FlatArray[string])(value), true
  1786  	case []time.Time:
  1787  		return &wrapSliceEncodePlan[time.Time]{}, (FlatArray[time.Time])(value), true
  1788  	}
  1789  
  1790  	if valueType := reflect.TypeOf(value); valueType != nil && valueType.Kind() == reflect.Slice {
  1791  		w := anySliceArrayReflect{
  1792  			slice: reflect.ValueOf(value),
  1793  		}
  1794  		return &wrapSliceEncodeReflectPlan{}, w, true
  1795  	}
  1796  
  1797  	return nil, nil, false
  1798  }
  1799  
  1800  type wrapSliceEncodePlan[T any] struct {
  1801  	next EncodePlan
  1802  }
  1803  
  1804  func (plan *wrapSliceEncodePlan[T]) SetNext(next EncodePlan) { plan.next = next }
  1805  
  1806  func (plan *wrapSliceEncodePlan[T]) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1807  	return plan.next.Encode((FlatArray[T])(value.([]T)), buf)
  1808  }
  1809  
  1810  type wrapSliceEncodeReflectPlan struct {
  1811  	next EncodePlan
  1812  }
  1813  
  1814  func (plan *wrapSliceEncodeReflectPlan) SetNext(next EncodePlan) { plan.next = next }
  1815  
  1816  func (plan *wrapSliceEncodeReflectPlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1817  	w := anySliceArrayReflect{
  1818  		slice: reflect.ValueOf(value),
  1819  	}
  1820  
  1821  	return plan.next.Encode(w, buf)
  1822  }
  1823  
  1824  func TryWrapMultiDimSliceEncodePlan(value any) (plan WrappedEncodePlanNextSetter, nextValue any, ok bool) {
  1825  	if _, ok := value.(driver.Valuer); ok {
  1826  		return nil, nil, false
  1827  	}
  1828  
  1829  	sliceValue := reflect.ValueOf(value)
  1830  	if sliceValue.Kind() == reflect.Slice {
  1831  		valueElemType := sliceValue.Type().Elem()
  1832  
  1833  		if valueElemType.Kind() == reflect.Slice {
  1834  			if !isRagged(sliceValue) {
  1835  				w := anyMultiDimSliceArray{
  1836  					slice: reflect.ValueOf(value),
  1837  				}
  1838  				return &wrapMultiDimSliceEncodePlan{}, &w, true
  1839  			}
  1840  		}
  1841  	}
  1842  
  1843  	return nil, nil, false
  1844  }
  1845  
  1846  type wrapMultiDimSliceEncodePlan struct {
  1847  	next EncodePlan
  1848  }
  1849  
  1850  func (plan *wrapMultiDimSliceEncodePlan) SetNext(next EncodePlan) { plan.next = next }
  1851  
  1852  func (plan *wrapMultiDimSliceEncodePlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1853  	w := anyMultiDimSliceArray{
  1854  		slice: reflect.ValueOf(value),
  1855  	}
  1856  
  1857  	return plan.next.Encode(&w, buf)
  1858  }
  1859  
  1860  func TryWrapArrayEncodePlan(value any) (plan WrappedEncodePlanNextSetter, nextValue any, ok bool) {
  1861  	if _, ok := value.(driver.Valuer); ok {
  1862  		return nil, nil, false
  1863  	}
  1864  
  1865  	if valueType := reflect.TypeOf(value); valueType != nil && valueType.Kind() == reflect.Array {
  1866  		w := anyArrayArrayReflect{
  1867  			array: reflect.ValueOf(value),
  1868  		}
  1869  		return &wrapArrayEncodeReflectPlan{}, w, true
  1870  	}
  1871  
  1872  	return nil, nil, false
  1873  }
  1874  
  1875  type wrapArrayEncodeReflectPlan struct {
  1876  	next EncodePlan
  1877  }
  1878  
  1879  func (plan *wrapArrayEncodeReflectPlan) SetNext(next EncodePlan) { plan.next = next }
  1880  
  1881  func (plan *wrapArrayEncodeReflectPlan) Encode(value any, buf []byte) (newBuf []byte, err error) {
  1882  	w := anyArrayArrayReflect{
  1883  		array: reflect.ValueOf(value),
  1884  	}
  1885  
  1886  	return plan.next.Encode(w, buf)
  1887  }
  1888  
  1889  func newEncodeError(value any, m *Map, oid uint32, formatCode int16, err error) error {
  1890  	var format string
  1891  	switch formatCode {
  1892  	case TextFormatCode:
  1893  		format = "text"
  1894  	case BinaryFormatCode:
  1895  		format = "binary"
  1896  	default:
  1897  		format = fmt.Sprintf("unknown (%d)", formatCode)
  1898  	}
  1899  
  1900  	var dataTypeName string
  1901  	if t, ok := m.TypeForOID(oid); ok {
  1902  		dataTypeName = t.Name
  1903  	} else {
  1904  		dataTypeName = "unknown type"
  1905  	}
  1906  
  1907  	return fmt.Errorf("unable to encode %#v into %s format for %s (OID %d): %w", value, format, dataTypeName, oid, err)
  1908  }
  1909  
  1910  // Encode appends the encoded bytes of value to buf. If value is the SQL value NULL then append nothing and return
  1911  // (nil, nil). The caller of Encode is responsible for writing the correct NULL value or the length of the data
  1912  // written.
  1913  func (m *Map) Encode(oid uint32, formatCode int16, value any, buf []byte) (newBuf []byte, err error) {
  1914  	if value == nil {
  1915  		return nil, nil
  1916  	}
  1917  
  1918  	plan := m.PlanEncode(oid, formatCode, value)
  1919  	if plan == nil {
  1920  		return nil, newEncodeError(value, m, oid, formatCode, errors.New("cannot find encode plan"))
  1921  	}
  1922  
  1923  	newBuf, err = plan.Encode(value, buf)
  1924  	if err != nil {
  1925  		return nil, newEncodeError(value, m, oid, formatCode, err)
  1926  	}
  1927  
  1928  	return newBuf, nil
  1929  }
  1930  
  1931  // SQLScanner returns a database/sql.Scanner for v. This is necessary for types like Array[T] and Range[T] where the
  1932  // type needs assistance from Map to implement the sql.Scanner interface. It is not necessary for types like Box that
  1933  // implement sql.Scanner directly.
  1934  //
  1935  // This uses the type of v to look up the PostgreSQL OID that v presumably came from. This means v must be registered
  1936  // with m by calling RegisterDefaultPgType.
  1937  func (m *Map) SQLScanner(v any) sql.Scanner {
  1938  	if s, ok := v.(sql.Scanner); ok {
  1939  		return s
  1940  	}
  1941  
  1942  	return &sqlScannerWrapper{m: m, v: v}
  1943  }
  1944  
  1945  type sqlScannerWrapper struct {
  1946  	m *Map
  1947  	v any
  1948  }
  1949  
  1950  func (w *sqlScannerWrapper) Scan(src any) error {
  1951  	t, ok := w.m.TypeForValue(w.v)
  1952  	if !ok {
  1953  		return fmt.Errorf("cannot convert to sql.Scanner: cannot find registered type for %T", w.v)
  1954  	}
  1955  
  1956  	var bufSrc []byte
  1957  	if src != nil {
  1958  		switch src := src.(type) {
  1959  		case string:
  1960  			bufSrc = []byte(src)
  1961  		case []byte:
  1962  			bufSrc = src
  1963  		default:
  1964  			bufSrc = []byte(fmt.Sprint(bufSrc))
  1965  		}
  1966  	}
  1967  
  1968  	return w.m.Scan(t.OID, TextFormatCode, bufSrc, w.v)
  1969  }
  1970  

View as plain text