From c7aba7c14efdbd9fc1bb44b4cb83bedee0c6a6fc Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Wed, 9 Dec 2020 12:40:37 -0500 Subject: Support subscripting of arbitrary types, not only arrays. This patch generalizes the subscripting infrastructure so that any data type can be subscripted, if it provides a handler function to define what that means. Traditional variable-length (varlena) arrays all use array_subscript_handler(), while the existing fixed-length types that support subscripting use raw_array_subscript_handler(). It's expected that other types that want to use subscripting notation will define their own handlers. (This patch provides no such new features, though; it only lays the foundation for them.) To do this, move the parser's semantic processing of subscripts (including coercion to whatever data type is required) into a method callback supplied by the handler. On the execution side, replace the ExecEvalSubscriptingRef* layer of functions with direct calls to callback-supplied execution routines. (Thus, essentially no new run-time overhead should be caused by this patch. Indeed, there is room to remove some overhead by supplying specialized execution routines. This patch does a little bit in that line, but more could be done.) Additional work is required here and there to remove formerly hard-wired assumptions about the result type, collation, etc of a SubscriptingRef expression node; and to remove assumptions that the subscript values must be integers. One useful side-effect of this is that we now have a less squishy mechanism for identifying whether a data type is a "true" array: instead of wiring in weird rules about typlen, we can look to see if pg_type.typsubscript == F_ARRAY_SUBSCRIPT_HANDLER. For this to be bulletproof, we have to forbid user-defined types from using that handler directly; but there seems no good reason for them to do so. This patch also removes assumptions that the number of subscripts is limited to MAXDIM (6), or indeed has any hard-wired limit. That limit still applies to types handled by array_subscript_handler or raw_array_subscript_handler, but to discourage other dependencies on this constant, I've moved it from c.h to utils/array.h. Dmitry Dolgov, reviewed at various times by Tom Lane, Arthur Zakirov, Peter Eisentraut, Pavel Stehule Discussion: https://postgr.es/m/CA+q6zcVDuGBv=M0FqBYX8DPebS3F_0KQ6OVFobGJPM507_SZ_w@mail.gmail.com Discussion: https://postgr.es/m/CA+q6zcVovR+XY4mfk-7oNk-rF91gH0PebnNfuUjuuDsyHjOcVA@mail.gmail.com --- doc/src/sgml/catalogs.sgml | 38 +++++++++++++------- doc/src/sgml/ref/create_type.sgml | 76 +++++++++++++++++++++++++++++++++------ 2 files changed, 90 insertions(+), 24 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 79069ddfabe..62711ee83ff 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -8740,6 +8740,21 @@ SCRAM-SHA-256$<iteration count>:&l + + + typsubscript regproc + (references pg_proc.oid) + + + Subscripting handler function's OID, or zero if this type doesn't + support subscripting. Types that are true array + types have typsubscript + = array_subscript_handler, but other types may + have other handler functions to implement specialized subscripting + behavior. + + + typelem oid @@ -8747,19 +8762,16 @@ SCRAM-SHA-256$<iteration count>:&l If typelem is not 0 then it - identifies another row in pg_type. - The current type can then be subscripted like an array yielding - values of type typelem. A - true array type is variable length - (typlen = -1), - but some fixed-length (typlen > 0) types - also have nonzero typelem, for example - name and point. - If a fixed-length type has a typelem then - its internal representation must be some number of values of the - typelem data type with no other data. - Variable-length array types have a header defined by the array - subroutines. + identifies another row in pg_type, + defining the type yielded by subscripting. This should be 0 + if typsubscript is 0. However, it can + be 0 when typsubscript isn't 0, if the + handler doesn't need typelem to + determine the subscripting result type. + Note that a typelem dependency is + considered to imply physical containment of the element type in + this type; so DDL changes on the element type might be restricted + by the presence of this type. diff --git a/doc/src/sgml/ref/create_type.sgml b/doc/src/sgml/ref/create_type.sgml index 970b517db9f..d909ee0d33b 100644 --- a/doc/src/sgml/ref/create_type.sgml +++ b/doc/src/sgml/ref/create_type.sgml @@ -43,6 +43,7 @@ CREATE TYPE name ( [ , TYPMOD_IN = type_modifier_input_function ] [ , TYPMOD_OUT = type_modifier_output_function ] [ , ANALYZE = analyze_function ] + [ , SUBSCRIPT = subscript_function ] [ , INTERNALLENGTH = { internallength | VARIABLE } ] [ , PASSEDBYVALUE ] [ , ALIGNMENT = alignment ] @@ -196,8 +197,9 @@ CREATE TYPE name receive_function, send_function, type_modifier_input_function, - type_modifier_output_function and - analyze_function + type_modifier_output_function, + analyze_function, and + subscript_function are optional. Generally these functions have to be coded in C or another low-level language. @@ -318,6 +320,26 @@ CREATE TYPE name in src/include/commands/vacuum.h. + + The optional subscript_function + allows the data type to be subscripted in SQL commands. Specifying this + function does not cause the type to be considered a true + array type; for example, it will not be a candidate for the result type + of ARRAY[] constructs. But if subscripting a value + of the type is a natural notation for extracting data from it, then + a subscript_function can + be written to define what that means. The subscript function must be + declared to take a single argument of type internal, and + return an internal result, which is a pointer to a struct + of methods (functions) that implement subscripting. + The detailed API for subscript functions appears + in src/include/nodes/subscripting.h; + it may also be useful to read the array implementation + in src/backend/utils/adt/arraysubs.c. + Additional information appears in + below. + + While the details of the new type's internal representation are only known to the I/O functions and other functions you create to work with @@ -428,11 +450,12 @@ CREATE TYPE name - To indicate that a type is an array, specify the type of the array + To indicate that a type is a fixed-length array type, + specify the type of the array elements using the ELEMENT key word. For example, to define an array of 4-byte integers (int4), specify - ELEMENT = int4. More details about array types - appear below. + ELEMENT = int4. For more details, + see below. @@ -456,7 +479,7 @@ CREATE TYPE name - + Array Types @@ -469,14 +492,16 @@ CREATE TYPE name repeated until a non-colliding name is found.) This implicitly-created array type is variable length and uses the built-in input and output functions array_in and - array_out. The array type tracks any changes in its + array_out. Furthermore, this type is what the system + uses for constructs such as ARRAY[] over the + user-defined type. The array type tracks any changes in its element type's owner or schema, and is dropped if the element type is. You might reasonably ask why there is an option, if the system makes the correct array type automatically. - The only case where it's useful to use is when you are + The main case where it's useful to use is when you are making a fixed-length type that happens to be internally an array of a number of identical things, and you want to allow these things to be accessed directly by subscripting, in addition to whatever operations you plan @@ -485,13 +510,32 @@ CREATE TYPE name using point[0] and point[1]. Note that this facility only works for fixed-length types whose internal form - is exactly a sequence of identical fixed-length fields. A subscriptable - variable-length type must have the generalized internal representation - used by array_in and array_out. + is exactly a sequence of identical fixed-length fields. For historical reasons (i.e., this is clearly wrong but it's far too late to change it), subscripting of fixed-length array types starts from zero, rather than from one as for variable-length arrays. + + + Specifying the option allows a data type to + be subscripted, even though the system does not otherwise regard it as + an array type. The behavior just described for fixed-length arrays is + actually implemented by the handler + function raw_array_subscript_handler, which is + used automatically if you specify for a + fixed-length type without also writing . + + + + When specifying a custom function, it is + not necessary to specify unless + the handler function needs to + consult typelem to find out what to return. + Be aware that specifying causes the system to + assume that the new type contains, or is somehow physically dependent on, + the element type; thus for example changing properties of the element + type won't be allowed if there are any columns of the dependent type. + @@ -654,6 +698,16 @@ CREATE TYPE name + + subscript_function + + + The name of a function that defines what subscripting a value of the + data type does. + + + + internallength -- cgit v1.2.3