| blob | 98f0f0c22215042582ad1a6fe6e912d543d11baa |
1 /*-------------------------------------------------------------------------
2 *
3 * arrayfuncs.c
4 * Support functions for arrays.
5 *
6 * Portions Copyright (c) 1996-2008, PostgreSQL Global Development Group
7 * Portions Copyright (c) 1994, Regents of the University of California
8 *
9 *
10 * IDENTIFICATION
11 * $PostgreSQL$
12 *
13 *-------------------------------------------------------------------------
14 */
17 #include <ctype.h>
30 /*
31 * GUC parameter
32 */
35 /*
36 * Local definitions
37 */
41 {
42 ARRAY_NO_LEVEL,
43 ARRAY_LEVEL_STARTED,
44 ARRAY_ELEM_STARTED,
45 ARRAY_ELEM_COMPLETED,
46 ARRAY_QUOTED_ELEM_STARTED,
47 ARRAY_QUOTED_ELEM_COMPLETED,
48 ARRAY_ELEM_DELIMITED,
49 ARRAY_LEVEL_COMPLETED,
50 ARRAY_LEVEL_DELIMITED
102 FunctionCallInfo fcinfo);
105 /*
106 * array_in :
107 * converts an array from the external format in "string" to
108 * its internal format.
109 *
110 * return value :
111 * the internal representation of the input array
112 */
113 Datum
115 {
118 * element */
124 Oid typioparam;
128 nitems;
132 int32 nbytes;
133 int32 dataoffset;
140 /*
141 * We arrange to look up info about element type, including its input
142 * conversion proc, only once per series of calls, assuming the element
143 * type doesn't change underneath us.
144 */
147 {
152 }
155 {
156 /*
157 * Get info about element type, including its input conversion proc
158 */
166 }
173 /* Make a modifiable copy of the input */
176 /*
177 * If the input string starts with dimension info, read and use that.
178 * Otherwise, we require the input to be in curly-brace style, and we
179 * prescan the input to determine dimensions.
180 *
181 * Dimension info takes the form of one or more [n] or [m:n] items. The
182 * outer loop iterates once per dimension item.
183 */
187 {
191 /*
192 * Note: we currently allow whitespace between, but not within,
193 * dimension items.
194 */
196 p++;
199 p++;
213 {
214 /* [m:n] format */
223 }
224 else
225 {
226 /* [n] format */
228 }
243 ndim++;
244 }
247 {
248 /* No array dimensions, so intuit dimensions from brace structure */
256 }
257 else
258 {
262 /* If array dimensions are given, expect '=' operator */
269 p++;
271 /*
272 * intuit dimensions from brace structure -- it better match what we
273 * were given
274 */
285 {
290 }
291 }
293 #ifdef ARRAYDEBUG
296 {
298 };
300 #endif
302 /* This checks for overflow of the array dimensions */
304 /* Empty array? */
313 typdelim,
318 {
321 }
322 else
323 {
326 }
345 }
347 /*
348 * ArrayCount
349 * Determines the dimensions for an array string.
350 *
351 * Returns number of dimensions as function result. The axis lengths are
352 * returned in dim[], which must be of size MAXDIM.
353 */
354 static int
356 {
358 i;
370 {
373 }
377 {
381 {
387 {
389 /* Signal a premature end of the string */
396 /*
397 * An escape must be after a level start, after an element
398 * start, or after an element delimiter. In any case we
399 * now must be past an element start.
400 */
410 /* skip the escaped character */
412 ptr++;
413 else
420 /*
421 * A quote must be after a level start, after a quoted
422 * element start, or after an element delimiter. In any
423 * case we now must be past an element start.
424 */
434 else
439 {
440 /*
441 * A left brace can occur if no nesting has occurred
442 * yet, after a level start, or after a level
443 * delimiter.
444 */
458 nest_level++;
461 }
465 {
466 /*
467 * A right brace can occur after an element start, an
468 * element completion, a quoted element completion, or
469 * a level completion.
470 */
484 nest_level--;
491 "array expressions with matching "
497 else
498 {
499 /*
500 * We don't set itemdone here; see comments in
501 * ReadArrayStr
502 */
504 }
505 }
509 {
511 {
512 /*
513 * Delimiters can occur after an element start, an
514 * element completion, a quoted element
515 * completion, or a level completion.
516 */
526 else
530 }
532 {
533 /*
534 * Other non-space characters must be after a
535 * level start, after an element start, or after
536 * an element delimiter. In any case we now must
537 * be past an element start.
538 */
546 }
547 }
549 }
551 ptr++;
552 }
554 ptr++;
555 }
557 /* only whitespace is allowed after the closing brace */
559 {
564 }
566 /* special case for an empty array */
574 }
576 /*
577 * ReadArrayStr :
578 * parses the array string pointed to by "arrayStr" and converts the values
579 * to internal format. Unspecified elements are initialized to nulls.
580 * The array dimensions must already have been determined.
581 *
582 * Inputs:
583 * arrayStr: the string to parse.
584 * CAUTION: the contents of "arrayStr" will be modified!
585 * origStr: the unmodified input string, used only in error messages.
586 * nitems: total number of array elements, as already determined.
587 * ndim: number of array dimensions
588 * dim[]: array axis lengths
589 * inputproc: type-specific input procedure for element datatype.
590 * typioparam, typmod: auxiliary values to pass to inputproc.
591 * typdelim: the value delimiter (type-specific).
592 * typlen, typbyval, typalign: storage parameters of element datatype.
593 *
594 * Outputs:
595 * values[]: filled with converted data values.
596 * nulls[]: filled with is-null markers.
597 * *hasnulls: set TRUE iff there are any null elements.
598 * *nbytes: set to total size of data area needed (including alignment
599 * padding but not including array header overhead).
600 *
601 * Note that values[] and nulls[] are allocated by the caller, and must have
602 * nitems elements.
603 */
604 static void
611 Oid typioparam,
612 int32 typmod,
621 {
628 int32 totbytes;
635 /* Initialize is-null markers to true */
638 /*
639 * We have to remove " and \ characters to create a clean item value to
640 * pass to the datatype input routine. We overwrite each item value
641 * in-place within arrayStr to do this. srcptr is the current scan point,
642 * and dstptr is where we are copying to.
643 *
644 * We also want to suppress leading and trailing unquoted whitespace. We
645 * use the leadingspace flag to suppress leading space. Trailing space is
646 * tracked by using dstendptr to point to the last significant output
647 * character.
648 *
649 * The error checking in this routine is mostly pro-forma, since we expect
650 * that ArrayCount() already validated the string.
651 */
654 {
666 {
668 {
670 /* Signal a premature end of the string */
674 origStr)));
677 /* Skip backslash, copy next character as-is. */
678 srcptr++;
683 origStr)));
685 /* Treat the escaped character as non-whitespace */
694 else
695 {
696 /*
697 * Advance dstendptr when we exit in_quotes; this
698 * saves having to do it in all the other in_quotes
699 * cases.
700 */
702 }
704 srcptr++;
708 {
713 origStr)));
714 nest_level++;
716 srcptr++;
717 }
718 else
723 {
728 origStr)));
732 nest_level--;
735 else
737 srcptr++;
738 }
739 else
746 {
751 srcptr++;
752 }
754 {
755 /*
756 * If leading space, drop it immediately. Else, copy
757 * but don't advance dstendptr.
758 */
760 srcptr++;
761 else
763 }
764 else
765 {
769 }
771 }
772 }
781 origStr)));
785 {
786 /* it's a NULL item */
790 }
791 else
792 {
796 }
797 }
799 /*
800 * Check for nulls, compute total data space needed
801 */
805 {
808 else
809 {
810 /* let's just make sure data is not toasted */
815 /* check for overflow of total request */
821 }
822 }
825 }
828 /*
829 * Copy data into an array object from a temporary array of Datums.
830 *
831 * array: array object (with header fields already filled in)
832 * values: array of Datums to be copied
833 * nulls: array of is-null flags (can be NULL if no nulls)
834 * nitems: number of Datums to be copied
835 * typbyval, typlen, typalign: info about element datatype
836 * freedata: if TRUE and element type is pass-by-ref, pfree data values
837 * referenced by Datums after copying them.
838 *
839 * If the input data is of varlena type, the caller must have ensured that
840 * the values are not toasted. (Doing it here doesn't work since the
841 * caller has already allocated space for the array...)
842 */
843 static void
852 {
863 {
865 {
868 /* bitmap bit stays 0 */
869 }
870 else
871 {
876 }
878 {
881 {
885 }
886 }
887 }
891 }
893 /*
894 * array_out :
895 * takes the internal representation of an array and returns a string
896 * containing the array in its external format.
897 */
898 Datum
900 {
913 /*
914 * 33 per dim since we assume 15 digits per number + ':' +'[]'
915 *
916 * +2 allows for assignment operator + trailing null
917 */
923 overall_length,
924 i,
925 j,
926 k,
933 /*
934 * We arrange to look up info about element type, including its output
935 * conversion proc, only once per series of calls, assuming the element
936 * type doesn't change underneath us.
937 */
940 {
945 }
948 {
949 /*
950 * Get info about element type, including its output conversion proc
951 */
959 }
971 {
974 }
976 /*
977 * we will need to add explicit dimensions if any dimension has a lower
978 * bound other than one
979 */
981 {
983 {
986 }
987 }
989 /*
990 * Convert all values to string form, count total space needed (including
991 * any overhead such as escaping backslashes), and detect whether each
992 * item needs double quotes.
993 */
1003 {
1006 /* Get source element, checking for NULL */
1008 {
1012 }
1013 else
1014 {
1015 Datum itemvalue;
1022 /* count data plus backslashes; detect chars needing quotes */
1027 else
1031 {
1036 {
1039 }
1043 }
1044 }
1048 /* Count the pair of double quotes, if needed */
1051 /* and the comma */
1054 /* advance bitmap pointer if any */
1056 {
1059 {
1060 bitmap++;
1062 }
1063 }
1064 }
1066 /*
1067 * count total number of curly braces in output string
1068 */
1074 /* add explicit dimensions if required */
1076 {
1080 {
1083 }
1086 }
1091 #define APPENDSTR(str) (strcpy(p, (str)), p += strlen(p))
1101 do
1102 {
1107 {
1110 {
1116 }
1119 }
1120 else
1125 {
1128 {
1131 }
1132 else
1134 }
1138 #undef APPENDSTR
1139 #undef APPENDCHAR
1145 }
1147 /*
1148 * array_recv :
1149 * converts an array from the external binary format to
1150 * its internal format.
1151 *
1152 * return value :
1153 * the internal representation of the input array
1154 */
1155 Datum
1157 {
1160 * element */
1162 Oid element_type;
1166 Oid typioparam;
1168 nitems;
1172 int32 nbytes;
1173 int32 dataoffset;
1176 flags,
1181 /* Get the array header information */
1201 {
1202 /* XXX Can we allow taking the input element type in any cases? */
1206 }
1209 {
1212 }
1214 /* This checks for overflow of array dimensions */
1217 /*
1218 * We arrange to look up info about element type, including its receive
1219 * conversion proc, only once per series of calls, assuming the element
1220 * type doesn't change underneath us.
1221 */
1224 {
1229 }
1232 {
1233 /* Get info about element type, including its receive proc */
1246 }
1249 {
1250 /* Return empty array ... but not till we've validated element_type */
1252 }
1267 {
1270 }
1271 else
1272 {
1275 }
1293 }
1295 /*
1296 * ReadArrayBinary:
1297 * collect the data elements of an array being read in binary style.
1298 *
1299 * Inputs:
1300 * buf: the data buffer to read from.
1301 * nitems: total number of array elements (already read).
1302 * receiveproc: type-specific receive procedure for element datatype.
1303 * typioparam, typmod: auxiliary values to pass to receiveproc.
1304 * typlen, typbyval, typalign: storage parameters of element datatype.
1305 *
1306 * Outputs:
1307 * values[]: filled with converted data values.
1308 * nulls[]: filled with is-null markers.
1309 * *hasnulls: set TRUE iff there are any null elements.
1310 * *nbytes: set to total size of data area needed (including alignment
1311 * padding but not including array header overhead).
1312 *
1313 * Note that values[] and nulls[] are allocated by the caller, and must have
1314 * nitems elements.
1315 */
1316 static void
1320 Oid typioparam,
1321 int32 typmod,
1329 {
1332 int32 totbytes;
1335 {
1337 StringInfoData elem_buf;
1340 /* Get and check the item length */
1348 {
1349 /* -1 length means NULL */
1354 }
1356 /*
1357 * Rather than copying data around, we just set up a phony StringInfo
1358 * pointing to the correct portion of the input buffer. We assume we
1359 * can scribble on the input buffer so as to maintain the convention
1360 * that StringInfos have a trailing null.
1361 */
1372 /* Now call the element's receiveproc */
1377 /* Trouble if it didn't eat the whole buffer */
1385 }
1387 /*
1388 * Check for nulls, compute total data space needed
1389 */
1393 {
1396 else
1397 {
1398 /* let's just make sure data is not toasted */
1403 /* check for overflow of total request */
1409 }
1410 }
1413 }
1416 /*
1417 * array_send :
1418 * takes the internal representation of an array and returns a bytea
1419 * containing the array in its external binary format.
1420 */
1421 Datum
1423 {
1433 i;
1436 StringInfoData buf;
1439 /*
1440 * We arrange to look up info about element type, including its send
1441 * conversion proc, only once per series of calls, assuming the element
1442 * type doesn't change underneath us.
1443 */
1446 {
1451 }
1454 {
1455 /* Get info about element type, including its send proc */
1468 }
1479 /* Send the array header information */
1484 {
1487 }
1489 /* Send the array elements using the element's own sendproc */
1495 {
1496 /* Get source element, checking for NULL */
1498 {
1499 /* -1 length means a NULL */
1501 }
1502 else
1503 {
1504 Datum itemvalue;
1516 }
1518 /* advance bitmap pointer if any */
1520 {
1523 {
1524 bitmap++;
1526 }
1527 }
1528 }
1531 }
1533 /*
1534 * array_dims :
1535 * returns the dimensions of the array pointed to by "v", as a "text"
1536 */
1537 Datum
1539 {
1546 /*
1547 * 33 since we assume 15 digits per number + ':' +'[]'
1548 *
1549 * +1 for trailing null
1550 */
1553 /* Sanity check: does it look like an array at all? */
1562 {
1565 }
1568 }
1570 /*
1571 * array_lower :
1572 * returns the lower dimension, of the DIM requested, for
1573 * the array pointed to by "v", as an int4
1574 */
1575 Datum
1577 {
1583 /* Sanity check: does it look like an array at all? */
1587 /* Sanity check: was the requested dim valid */
1595 }
1597 /*
1598 * array_upper :
1599 * returns the upper dimension, of the DIM requested, for
1600 * the array pointed to by "v", as an int4
1601 */
1602 Datum
1604 {
1611 /* Sanity check: does it look like an array at all? */
1615 /* Sanity check: was the requested dim valid */
1625 }
1627 /*
1628 * array_ref :
1629 * This routine takes an array pointer and a subscript array and returns
1630 * the referenced item as a Datum. Note that for a pass-by-reference
1631 * datatype, the returned Datum is a pointer into the array object.
1632 *
1633 * This handles both ordinary varlena arrays and fixed-length arrays.
1634 *
1635 * Inputs:
1636 * array: the array object (mustn't be NULL)
1637 * nSubscripts: number of subscripts supplied
1638 * indx[]: the subscript values
1639 * arraytyplen: pg_type.typlen for the array type
1640 * elmlen: pg_type.typlen for the array's element type
1641 * elmbyval: pg_type.typbyval for the array's element type
1642 * elmalign: pg_type.typalign for the array's element type
1643 *
1644 * Outputs:
1645 * The return value is the element Datum.
1646 * *isNull is set to indicate whether the element is NULL.
1647 */
1648 Datum
1657 {
1659 ndim,
1662 offset,
1670 {
1671 /*
1672 * fixed-length arrays -- these are assumed to be 1-d, 0-based
1673 */
1681 }
1682 else
1683 {
1684 /* detoast input array if necessary */
1692 }
1694 /*
1695 * Return NULL for invalid subscript
1696 */
1698 {
1701 }
1703 {
1705 {
1708 }
1709 }
1711 /*
1712 * Calculate the element number
1713 */
1716 /*
1717 * Check for NULL array element
1718 */
1720 {
1723 }
1725 /*
1726 * OK, get the element
1727 */
1732 }
1734 /*
1735 * array_get_slice :
1736 * This routine takes an array and a range of indices (upperIndex and
1737 * lowerIndx), creates a new array structure for the referred elements
1738 * and returns a pointer to it.
1739 *
1740 * This handles both ordinary varlena arrays and fixed-length arrays.
1741 *
1742 * Inputs:
1743 * array: the array object (mustn't be NULL)
1744 * nSubscripts: number of subscripts supplied (must be same for upper/lower)
1745 * upperIndx[]: the upper subscript values
1746 * lowerIndx[]: the lower subscript values
1747 * arraytyplen: pg_type.typlen for the array type
1748 * elmlen: pg_type.typlen for the array's element type
1749 * elmbyval: pg_type.typbyval for the array's element type
1750 * elmalign: pg_type.typalign for the array's element type
1751 *
1752 * Outputs:
1753 * The return value is the new array Datum (it's never NULL)
1754 *
1755 * NOTE: we assume it is OK to scribble on the provided subscript arrays
1756 * lowerIndx[] and upperIndx[]. These are generally just temporaries.
1757 */
1758 ArrayType *
1767 {
1770 ndim,
1776 Oid elemtype;
1779 int32 dataoffset;
1784 {
1785 /*
1786 * fixed-length arrays -- currently, cannot slice these because parser
1787 * labels output as being of the fixed-length array type! Code below
1788 * shows how we could support it if the parser were changed to label
1789 * output as a suitable varlena array type.
1790 */
1795 /*
1796 * fixed-length arrays -- these are assumed to be 1-d, 0-based
1797 *
1798 * XXX where would we get the correct ELEMTYPE from?
1799 */
1808 }
1809 else
1810 {
1811 /* detoast input array if necessary */
1820 }
1822 /*
1823 * Check provided subscripts. A slice exceeding the current array limits
1824 * is silently truncated to the array limits. If we end up with an empty
1825 * slice, return an empty array.
1826 */
1831 {
1838 }
1839 /* fill any missing subscript positions with full array range */
1841 {
1846 }
1855 /*
1856 * Currently, we put a null bitmap in the result if the source has one;
1857 * could be smarter ...
1858 */
1860 {
1863 }
1864 else
1865 {
1868 }
1877 /*
1878 * Lower bounds of the new array are set to 1. Formerly (before 7.3) we
1879 * copied the given lowerIndx values ... but that seems confusing.
1880 */
1892 }
1894 /*
1895 * array_set :
1896 * This routine sets the value of an array element (specified by
1897 * a subscript array) to a new value specified by "dataValue".
1898 *
1899 * This handles both ordinary varlena arrays and fixed-length arrays.
1900 *
1901 * Inputs:
1902 * array: the initial array object (mustn't be NULL)
1903 * nSubscripts: number of subscripts supplied
1904 * indx[]: the subscript values
1905 * dataValue: the datum to be inserted at the given position
1906 * isNull: whether dataValue is NULL
1907 * arraytyplen: pg_type.typlen for the array type
1908 * elmlen: pg_type.typlen for the array's element type
1909 * elmbyval: pg_type.typbyval for the array's element type
1910 * elmalign: pg_type.typalign for the array's element type
1911 *
1912 * Result:
1913 * A new array is returned, just like the old except for the one
1914 * modified entry. The original array object is not changed.
1915 *
1916 * For one-dimensional arrays only, we allow the array to be extended
1917 * by assigning to a position outside the existing subscript range; any
1918 * positions between the existing elements and the new one are set to NULLs.
1919 * (XXX TODO: allow a corresponding behavior for multidimensional arrays)
1920 *
1921 * NOTE: For assignments, we throw an error for invalid subscripts etc,
1922 * rather than returning a NULL as the fetch operations do.
1923 */
1924 ArrayType *
1928 Datum dataValue,
1934 {
1937 ndim,
1940 offset;
1945 newnitems,
1946 olddatasize,
1947 newsize,
1948 olditemlen,
1949 newitemlen,
1950 overheadlen,
1951 oldoverheadlen,
1952 addedbefore,
1953 addedafter,
1954 lenbefore,
1955 lenafter;
1958 {
1959 /*
1960 * fixed-length arrays -- these are assumed to be 1-d, 0-based. We
1961 * cannot extend them, either.
1962 */
1983 }
1990 /* make sure item to be inserted is not toasted */
1994 /* detoast input array if necessary */
1999 /*
2000 * if number of dims is zero, i.e. an empty array, create an array with
2001 * nSubscripts dimensions, and set the lower bounds to the supplied
2002 * subscripts
2003 */
2005 {
2009 {
2012 }
2017 }
2024 /* copy dim/lb since we may modify them */
2031 /*
2032 * Check subscripts
2033 */
2035 {
2037 {
2043 }
2045 {
2050 }
2051 }
2052 else
2053 {
2054 /*
2055 * XXX currently we do not support extending multi-dimensional arrays
2056 * during assignment
2057 */
2059 {
2065 }
2066 }
2068 /*
2069 * Compute sizes of items and areas to copy
2070 */
2074 else
2081 {
2086 }
2088 {
2093 }
2094 else
2095 {
2102 else
2103 {
2106 }
2108 }
2112 else
2113 {
2116 }
2120 /*
2121 * OK, create the new array and fill in header/dimensions
2122 */
2131 /*
2132 * Fill in data
2133 */
2136 lenbefore);
2142 lenafter);
2144 /*
2145 * Fill in nulls bitmap if needed
2146 *
2147 * Note: it's possible we just replaced the last NULL with a non-NULL, and
2148 * could get rid of the bitmap. Seems not worth testing for though.
2149 */
2151 {
2154 /* Zero the bitmap to take care of marking inserted positions null */
2156 /* Fix the inserted value */
2159 else
2161 /* Fix the copied range(s) */
2165 oldnitems);
2166 else
2167 {
2170 offset);
2175 }
2176 }
2179 }
2181 /*
2182 * array_set_slice :
2183 * This routine sets the value of a range of array locations (specified
2184 * by upper and lower subscript values) to new values passed as
2185 * another array.
2186 *
2187 * This handles both ordinary varlena arrays and fixed-length arrays.
2188 *
2189 * Inputs:
2190 * array: the initial array object (mustn't be NULL)
2191 * nSubscripts: number of subscripts supplied (must be same for upper/lower)
2192 * upperIndx[]: the upper subscript values
2193 * lowerIndx[]: the lower subscript values
2194 * srcArray: the source for the inserted values
2195 * isNull: indicates whether srcArray is NULL
2196 * arraytyplen: pg_type.typlen for the array type
2197 * elmlen: pg_type.typlen for the array's element type
2198 * elmbyval: pg_type.typbyval for the array's element type
2199 * elmalign: pg_type.typalign for the array's element type
2200 *
2201 * Result:
2202 * A new array is returned, just like the old except for the
2203 * modified range. The original array object is not changed.
2204 *
2205 * For one-dimensional arrays only, we allow the array to be extended
2206 * by assigning to positions outside the existing subscript range; any
2207 * positions between the existing elements and the new ones are set to NULLs.
2208 * (XXX TODO: allow a corresponding behavior for multidimensional arrays)
2209 *
2210 * NOTE: we assume it is OK to scribble on the provided index arrays
2211 * lowerIndx[] and upperIndx[]. These are generally just temporaries.
2212 *
2213 * NOTE: For assignments, we throw an error for silly subscripts etc,
2214 * rather than returning a NULL or empty array as the fetch operations do.
2215 */
2216 ArrayType *
2227 {
2230 ndim,
2236 nsrcitems,
2237 olddatasize,
2238 newsize,
2239 olditemsize,
2240 newitemsize,
2241 overheadlen,
2242 oldoverheadlen,
2243 addedbefore,
2244 addedafter,
2245 lenbefore,
2246 lenafter,
2247 itemsbefore,
2248 itemsafter,
2249 nolditems;
2251 /* Currently, assignment from a NULL source array is a no-op */
2256 {
2257 /*
2258 * fixed-length arrays -- not got round to doing this...
2259 */
2263 }
2265 /* detoast arrays if necessary */
2269 /* note: we assume srcArray contains no toasted elements */
2273 /*
2274 * if number of dims is zero, i.e. an empty array, create an array with
2275 * nSubscripts dimensions, and set the upper and lower bounds to the
2276 * supplied subscripts
2277 */
2279 {
2289 {
2292 }
2294 /* complain if too few source items; we ignore extras, however */
2303 }
2310 /* copy dim/lb since we may modify them */
2317 /*
2318 * Check subscripts
2319 */
2321 {
2328 {
2334 }
2336 {
2341 }
2342 }
2343 else
2344 {
2345 /*
2346 * XXX currently we do not support extending multi-dimensional arrays
2347 * during assignment
2348 */
2350 {
2360 }
2361 /* fill any missing subscript positions with full array range */
2363 {
2370 }
2371 }
2373 /* Do this mainly to check for overflow */
2376 /*
2377 * Make sure source array has enough entries. Note we ignore the shape of
2378 * the source array and just read entries serially.
2379 */
2387 /*
2388 * Compute space occupied by new entries, space occupied by replaced
2389 * entries, and required space for new array.
2390 */
2393 else
2401 {
2402 /*
2403 * here we do not need to cope with extension of the array; it would
2404 * be a lot more complicated if we had to do so...
2405 */
2413 }
2414 else
2415 {
2416 /*
2417 * here we must allow for possibility of slice larger than orig array
2418 */
2428 itemsbefore,
2431 {
2434 }
2435 else
2436 {
2440 nolditems,
2442 }
2445 }
2458 {
2459 /*
2460 * here we do not need to cope with extension of the array; it would
2461 * be a lot more complicated if we had to do so...
2462 */
2467 }
2468 else
2469 {
2470 /* fill in data */
2473 lenbefore);
2476 newitemsize);
2479 lenafter);
2480 /* fill in nulls bitmap if needed */
2482 {
2486 /* Zero the bitmap to handle marking inserted positions null */
2490 itemsbefore);
2493 nsrcitems);
2496 itemsafter);
2497 }
2498 }
2501 }
2503 /*
2504 * array_map()
2505 *
2506 * Map an array through an arbitrary function. Return a new array with
2507 * same dimensions and each source element transformed by fn(). Each
2508 * source element is passed as the first argument to fn(); additional
2509 * arguments to be passed to fn() can be specified by the caller.
2510 * The output array can have a different element type than the input.
2511 *
2512 * Parameters are:
2513 * * fcinfo: a function-call data structure pre-constructed by the caller
2514 * to be ready to call the desired function, with everything except the
2515 * first argument position filled in. In particular, flinfo identifies
2516 * the function fn(), and if nargs > 1 then argument positions after the
2517 * first must be preset to the additional values to be passed. The
2518 * first argument position initially holds the input array value.
2519 * * inpType: OID of element type of input array. This must be the same as,
2520 * or binary-compatible with, the first argument type of fn().
2521 * * retType: OID of element type of output array. This must be the same as,
2522 * or binary-compatible with, the result type of fn().
2523 * * amstate: workspace for array_map. Must be zeroed by caller before
2524 * first call, and not touched after that.
2525 *
2526 * It is legitimate to pass a freshly-zeroed ArrayMapState on each call,
2527 * but better performance can be had if the state can be preserved across
2528 * a series of calls.
2529 *
2530 * NB: caller must assure that input array is not NULL. NULL elements in
2531 * the array are OK however.
2532 */
2533 Datum
2536 {
2541 Datum elt;
2547 int32 dataoffset;
2561 /* Get input array */
2574 /* Check for empty array */
2576 {
2577 /* Return empty array */
2579 }
2581 /*
2582 * We arrange to look up info about input and return element types only
2583 * once per series of calls, assuming the element type doesn't change
2584 * underneath us.
2585 */
2590 {
2596 }
2602 {
2608 }
2613 /* Allocate temporary arrays for new values */
2617 /* Loop over source data */
2624 {
2627 /* Get source element, checking for NULL */
2629 {
2631 }
2632 else
2633 {
2639 }
2641 /*
2642 * Apply the given function to source elt and extra args.
2643 */
2645 {
2649 {
2651 {
2654 }
2655 }
2656 }
2659 {
2662 }
2663 else
2669 else
2670 {
2671 /* Ensure data is not toasted */
2674 /* Update total result size */
2677 /* check for overflow of total request */
2683 }
2685 /* advance bitmap pointer if any */
2687 {
2690 {
2691 bitmap++;
2693 }
2694 }
2695 }
2697 /* Allocate and initialize the result array */
2699 {
2702 }
2703 else
2704 {
2707 }
2715 /*
2716 * Note: do not risk trying to pfree the results of the called function
2717 */
2727 }
2729 /*
2730 * construct_array --- simple method for constructing an array object
2731 *
2732 * elems: array of Datum items to become the array contents
2733 * (NULL element values are not supported).
2734 * nelems: number of items
2735 * elmtype, elmlen, elmbyval, elmalign: info for the datatype of the items
2736 *
2737 * A palloc'd 1-D array object is constructed and returned. Note that
2738 * elem values will be copied into the object even if pass-by-ref type.
2739 *
2740 * NOTE: it would be cleaner to look up the elmlen/elmbval/elmalign info
2741 * from the system catalogs, given the elmtype. However, the caller is
2742 * in a better position to cache this info across multiple uses, or even
2743 * to hard-wire values if the element type is hard-wired.
2744 */
2745 ArrayType *
2747 Oid elmtype,
2749 {
2758 }
2760 /*
2761 * construct_md_array --- simple method for constructing an array object
2762 * with arbitrary dimensions and possible NULLs
2763 *
2764 * elems: array of Datum items to become the array contents
2765 * nulls: array of is-null flags (can be NULL if no nulls)
2766 * ndims: number of dimensions
2767 * dims: integer array with size of each dimension
2768 * lbs: integer array with lower bound of each dimension
2769 * elmtype, elmlen, elmbyval, elmalign: info for the datatype of the items
2770 *
2771 * A palloc'd ndims-D array object is constructed and returned. Note that
2772 * elem values will be copied into the object even if pass-by-ref type.
2773 *
2774 * NOTE: it would be cleaner to look up the elmlen/elmbval/elmalign info
2775 * from the system catalogs, given the elmtype. However, the caller is
2776 * in a better position to cache this info across multiple uses, or even
2777 * to hard-wire values if the element type is hard-wired.
2778 */
2779 ArrayType *
2786 {
2789 int32 nbytes;
2790 int32 dataoffset;
2804 /* fast track for empty array */
2810 /* compute required space */
2814 {
2816 {
2819 }
2820 /* make sure data is not toasted */
2825 /* check for overflow of total request */
2831 }
2833 /* Allocate and initialize result array */
2835 {
2838 }
2839 else
2840 {
2843 }
2858 }
2860 /*
2861 * construct_empty_array --- make a zero-dimensional array of given type
2862 */
2863 ArrayType *
2865 {
2874 }
2876 /*
2877 * deconstruct_array --- simple method for extracting data from an array
2878 *
2879 * array: array object to examine (must not be NULL)
2880 * elmtype, elmlen, elmbyval, elmalign: info for the datatype of the items
2881 * elemsp: return value, set to point to palloc'd array of Datum values
2882 * nullsp: return value, set to point to palloc'd array of isnull markers
2883 * nelemsp: return value, set to number of extracted values
2884 *
2885 * The caller may pass nullsp == NULL if it does not support NULLs in the
2886 * array. Note that this produces a very uninformative error message,
2887 * so do it only in cases where a NULL is really not expected.
2888 *
2889 * If array elements are pass-by-ref data type, the returned Datums will
2890 * be pointers into the array object.
2891 *
2892 * NOTE: it would be cleaner to look up the elmlen/elmbval/elmalign info
2893 * from the system catalogs, given the elmtype. However, in most current
2894 * uses the type is hard-wired into the caller and so we can save a lookup
2895 * cycle by hard-wiring the type info as well.
2896 */
2897 void
2899 Oid elmtype,
2902 {
2917 else
2926 {
2927 /* Get source element, checking for NULL */
2929 {
2933 else
2937 }
2938 else
2939 {
2945 }
2947 /* advance bitmap pointer if any */
2949 {
2952 {
2953 bitmap++;
2955 }
2956 }
2957 }
2958 }
2961 /*
2962 * array_eq :
2963 * compares two arrays for equality
2964 * result :
2965 * returns true if the arrays are equal, false otherwise.
2966 *
2967 * Note: we do not use array_cmp here, since equality may be meaningful in
2968 * datatypes that don't have a total ordering (and hence no btree support).
2969 */
2970 Datum
2972 {
2992 FunctionCallInfoData locfcinfo;
2999 /* fast path if the arrays do not have the same dimensionality */
3003 else
3004 {
3005 /*
3006 * We arrange to look up the equality function only once per series of
3007 * calls, assuming the element type doesn't change underneath us. The
3008 * typcache is used so that we have no memory leakage when being used
3009 * as an index support function.
3010 */
3014 {
3016 TYPECACHE_EQ_OPR_FINFO);
3023 }
3028 /*
3029 * apply the operator to each pair of array elements.
3030 */
3034 /* Loop over source data */
3043 {
3044 Datum elt1;
3045 Datum elt2;
3050 /* Get elements, checking for NULL */
3052 {
3055 }
3056 else
3057 {
3062 }
3065 {
3068 }
3069 else
3070 {
3075 }
3077 /* advance bitmap pointers if any */
3080 {
3082 bitmap1++;
3084 bitmap2++;
3086 }
3088 /*
3089 * We consider two NULLs equal; NULL and not-NULL are unequal.
3090 */
3094 {
3097 }
3099 /*
3100 * Apply the operator to the element pair
3101 */
3109 {
3112 }
3113 }
3114 }
3116 /* Avoid leaking memory when handed toasted input. */
3121 }
3124 /*-----------------------------------------------------------------------------
3125 * array-array bool operators:
3126 * Given two arrays, iterate comparison operators
3127 * over the array. Uses logic similar to text comparison
3128 * functions, except element-by-element instead of
3129 * character-by-character.
3130 *----------------------------------------------------------------------------
3131 */
3133 Datum
3135 {
3137 }
3139 Datum
3141 {
3143 }
3145 Datum
3147 {
3149 }
3151 Datum
3153 {
3155 }
3157 Datum
3159 {
3161 }
3163 Datum
3165 {
3167 }
3169 /*
3170 * array_cmp()
3171 * Internal comparison function for arrays.
3172 *
3173 * Returns -1, 0 or 1
3174 */
3175 static int
3177 {
3199 FunctionCallInfoData locfcinfo;
3206 /*
3207 * We arrange to look up the comparison function only once per series of
3208 * calls, assuming the element type doesn't change underneath us. The
3209 * typcache is used so that we have no memory leakage when being used as
3210 * an index support function.
3211 */
3215 {
3217 TYPECACHE_CMP_PROC_FINFO);
3224 }
3229 /*
3230 * apply the operator to each pair of array elements.
3231 */
3235 /* Loop over source data */
3244 {
3245 Datum elt1;
3246 Datum elt2;
3249 int32 cmpresult;
3251 /* Get elements, checking for NULL */
3253 {
3256 }
3257 else
3258 {
3263 }
3266 {
3269 }
3270 else
3271 {
3276 }
3278 /* advance bitmap pointers if any */
3281 {
3283 bitmap1++;
3285 bitmap2++;
3287 }
3289 /*
3290 * We consider two NULLs equal; NULL > not-NULL.
3291 */
3295 {
3296 /* arg1 is greater than arg2 */
3299 }
3301 {
3302 /* arg1 is less than arg2 */
3305 }
3307 /* Compare the pair of elements */
3319 {
3320 /* arg1 is less than arg2 */
3323 }
3324 else
3325 {
3326 /* arg1 is greater than arg2 */
3329 }
3330 }
3332 /*
3333 * If arrays contain same data (up to end of shorter one), apply
3334 * additional rules to sort by dimensionality. The relative significance
3335 * of the different bits of information is historical; mainly we just care
3336 * that we don't say "equal" for arrays of different dimensionality.
3337 */
3339 {
3344 else
3345 {
3346 /* this relies on LB array immediately following DIMS array */
3348 {
3350 {
3353 }
3354 }
3355 }
3356 }
3358 /* Avoid leaking memory when handed toasted input. */
3363 }
3366 /*-----------------------------------------------------------------------------
3367 * array overlap/containment comparisons
3368 * These use the same methods of comparing array elements as array_eq.
3369 * We consider only the elements of the arrays, ignoring dimensionality.
3370 *----------------------------------------------------------------------------
3371 */
3373 /*
3374 * array_contain_compare :
3375 * compares two arrays for overlap/containment
3376 *
3377 * When matchall is true, return true if all members of array1 are in array2.
3378 * When matchall is false, return true if any members of array1 are in array2.
3379 */
3380 static bool
3383 {
3399 FunctionCallInfoData locfcinfo;
3406 /*
3407 * We arrange to look up the equality function only once per series of
3408 * calls, assuming the element type doesn't change underneath us. The
3409 * typcache is used so that we have no memory leakage when being used as
3410 * an index support function.
3411 */
3415 {
3417 TYPECACHE_EQ_OPR_FINFO);
3424 }
3429 /*
3430 * Since we probably will need to scan array2 multiple times, it's
3431 * worthwhile to use deconstruct_array on it. We scan array1 the hard way
3432 * however, since we very likely won't need to look at all of it.
3433 */
3437 /*
3438 * Apply the comparison operator to each pair of array elements.
3439 */
3443 /* Loop over source data */
3450 {
3451 Datum elt1;
3454 /* Get element, checking for NULL */
3456 {
3459 }
3460 else
3461 {
3466 }
3468 /* advance bitmap pointer if any */
3471 {
3473 bitmap1++;
3475 }
3477 /*
3478 * We assume that the comparison operator is strict, so a NULL can't
3479 * match anything. XXX this diverges from the "NULL=NULL" behavior of
3480 * array_eq, should we act like that?
3481 */
3483 {
3485 {
3488 }
3490 }
3493 {
3501 /*
3502 * Apply the operator to the element pair
3503 */
3512 }
3515 {
3516 /* found a match for elt1 */
3518 {
3521 }
3522 }
3523 else
3524 {
3525 /* no match for elt1 */
3527 {
3530 }
3531 }
3532 }
3538 }
3540 Datum
3542 {
3550 /* Avoid leaking memory when handed toasted input. */
3555 }
3557 Datum
3559 {
3567 /* Avoid leaking memory when handed toasted input. */
3572 }
3574 Datum
3576 {
3584 /* Avoid leaking memory when handed toasted input. */
3589 }
3592 /***************************************************************************/
3593 /******************| Support Routines |*****************/
3594 /***************************************************************************/
3596 /*
3597 * Check whether a specific array element is NULL
3598 *
3599 * nullbitmap: pointer to array's null bitmap (NULL if none)
3600 * offset: 0-based linear element number of array element
3601 */
3602 static bool
3604 {
3610 }
3612 /*
3613 * Set a specific array element's null-bitmap entry
3614 *
3615 * nullbitmap: pointer to array's null bitmap (mustn't be NULL)
3616 * offset: 0-based linear element number of array element
3617 * isNull: null status to set
3618 */
3619 static void
3621 {
3628 else
3630 }
3632 /*
3633 * Fetch array element at pointer, converted correctly to a Datum
3634 *
3635 * Caller must have handled case of NULL element
3636 */
3637 static Datum
3639 {
3641 }
3643 /*
3644 * Copy datum to *dest and return total space used (including align padding)
3645 *
3646 * Caller must have handled case of NULL element
3647 */
3648 static int
3654 {
3658 {
3661 else
3664 }
3665 else
3666 {
3671 }
3674 }
3676 /*
3677 * Advance ptr over nitems array elements
3678 *
3679 * ptr: starting location in array
3680 * offset: 0-based linear element number of first element (the one at *ptr)
3681 * nullbitmap: start of array's null bitmap, or NULL if none
3682 * nitems: number of array elements to advance over (>= 0)
3683 * typlen, typbyval, typalign: storage parameters of array element datatype
3684 *
3685 * It is caller's responsibility to ensure that nitems is within range
3686 */
3690 {
3694 /* easy if fixed-size elements and no NULLs */
3698 /* seems worth having separate loops for NULL and no-NULLs cases */
3700 {
3705 {
3707 {
3710 }
3713 {
3714 nullbitmap++;
3716 }
3717 }
3718 }
3719 else
3720 {
3722 {
3725 }
3726 }
3728 }
3730 /*
3731 * Compute total size of the nitems array elements starting at *ptr
3732 *
3733 * Parameters same as for array_seek
3734 */
3735 static int
3738 {
3741 }
3743 /*
3744 * Copy nitems array elements from srcptr to destptr
3745 *
3746 * destptr: starting destination location (must be enough room!)
3747 * nitems: number of array elements to copy (>= 0)
3748 * srcptr: starting location in source array
3749 * offset: 0-based linear element number of first element (the one at *srcptr)
3750 * nullbitmap: start of source array's null bitmap, or NULL if none
3751 * typlen, typbyval, typalign: storage parameters of array element datatype
3752 *
3753 * Returns number of bytes copied
3754 *
3755 * NB: this does not take care of setting up the destination's null bitmap!
3756 */
3757 static int
3761 {
3768 }
3770 /*
3771 * Copy nitems null-bitmap bits from source to destination
3772 *
3773 * destbitmap: start of destination array's null bitmap (mustn't be NULL)
3774 * destoffset: 0-based linear element number of first dest element
3775 * srcbitmap: start of source array's null bitmap, or NULL if none
3776 * srcoffset: 0-based linear element number of first source element
3777 * nitems: number of bits to copy (>= 0)
3778 *
3779 * If srcbitmap is NULL then we assume the source is all-non-NULL and
3780 * fill 1's into the destination bitmap. Note that only the specified
3781 * bits in the destination map are changed, not any before or after.
3782 *
3783 * Note: this could certainly be optimized using standard bitblt methods.
3784 * However, it's not clear that the typical Postgres array has enough elements
3785 * to make it worth worrying too much. For the moment, KISS.
3786 */
3787 void
3791 {
3793 destbitval,
3794 srcbitmask,
3795 srcbitval;
3804 {
3809 {
3812 else
3816 {
3821 }
3824 {
3825 srcbitmap++;
3829 }
3830 }
3833 }
3834 else
3835 {
3837 {
3841 {
3846 }
3847 }
3850 }
3851 }
3853 /*
3854 * Compute space needed for a slice of an array
3855 *
3856 * We assume the caller has verified that the slice coordinates are valid.
3857 */
3858 static int
3863 {
3871 j,
3872 inc;
3877 /* Pretty easy for fixed element length without nulls ... */
3881 /* Else gotta do it the hard way */
3890 do
3891 {
3893 {
3897 }
3899 {
3904 }
3905 src_offset++;
3908 }
3910 /*
3911 * Extract a slice of an array into consecutive elements in the destination
3912 * array.
3913 *
3914 * We assume the caller has verified that the slice coordinates are valid,
3915 * allocated enough storage for the result, and initialized the header
3916 * of the new array.
3917 */
3918 static void
3930 {
3935 dest_offset,
3941 j,
3942 inc;
3954 do
3955 {
3957 {
3958 /* skip unwanted elements */
3963 }
3973 src_offset++;
3974 dest_offset++;
3976 }
3978 /*
3979 * Insert a slice into an array.
3980 *
3981 * ndim/dim[]/lb[] are dimensions of the original array. A new array with
3982 * those same dimensions is to be constructed. destArray must already
3983 * have been allocated and its header initialized.
3984 *
3985 * st[]/endp[] identify the slice to be replaced. Elements within the slice
3986 * volume are taken from consecutive elements of the srcArray; elements
3987 * outside it are copied from origArray.
3988 *
3989 * We assume the caller has verified that the slice coordinates are valid.
3990 */
3991 static void
4003 {
4013 orig_offset,
4014 src_offset,
4020 j,
4021 inc;
4024 /* copy items before the slice start */
4040 do
4041 {
4042 /* Copy/advance over elements between here and next part of slice */
4044 {
4056 }
4057 /* Copy new element at this slice position */
4067 dest_offset++;
4068 src_offset++;
4069 /* Advance over old element at this slice position */
4072 orig_offset++;
4075 /* don't miss any data at the end */
4083 }
4085 /*
4086 * accumArrayResult - accumulate one (more) Datum for an array result
4087 *
4088 * astate is working state (NULL on first call)
4089 * rcontext is where to keep working state
4090 */
4091 ArrayBuildState *
4094 Oid element_type,
4095 MemoryContext rcontext)
4096 {
4097 MemoryContext arr_context,
4098 oldcontext;
4101 {
4102 /* First time through --- initialize */
4104 /* Make a temporary context to hold all the junk */
4107 ALLOCSET_DEFAULT_MINSIZE,
4108 ALLOCSET_DEFAULT_INITSIZE,
4109 ALLOCSET_DEFAULT_MAXSIZE);
4122 }
4123 else
4124 {
4127 /* enlarge dvalues[]/dnulls[] if needed */
4129 {
4135 }
4136 }
4138 /* Use datumCopy to ensure pass-by-ref stuff is copied into mcontext */
4149 }
4151 /*
4152 * makeArrayResult - produce 1-D final result of accumArrayResult
4153 *
4154 * astate is working state (not NULL)
4155 * rcontext is where to construct result
4156 */
4157 Datum
4159 MemoryContext rcontext)
4160 {
4168 }
4170 /*
4171 * makeMdArrayResult - produce multi-D final result of accumArrayResult
4172 *
4173 * beware: no check that specified dimensions match the number of values
4174 * accumulated.
4175 *
4176 * astate is working state (not NULL)
4177 * rcontext is where to construct result
4178 */
4179 Datum
4184 MemoryContext rcontext)
4185 {
4187 MemoryContext oldcontext;
4189 /* Build the final array result in rcontext */
4194 ndims,
4195 dims,
4196 lbs,
4204 /* Clean up all the junk */
4208 }
4210 Datum
4212 {
4223 }
4225 Datum
4227 {
4238 }
4242 {
4243 int4 lower;
4244 int4 upper;
4248 /*
4249 * generate_subscripts(array anyarray, dim int [, reverse bool])
4250 * Returns all subscripts of the array for any dimension
4251 */
4252 Datum
4254 {
4256 MemoryContext oldcontext;
4259 /* stuff done only on the first call of the function */
4261 {
4267 /* create a function context for cross-call persistence */
4270 /* Sanity check: does it look like an array at all? */
4274 /* Sanity check: was the requested dim valid */
4278 /*
4279 * switch to memory context appropriate for multiple function calls
4280 */
4294 }
4301 {
4304 else
4306 }
4307 else
4308 /* done when there are no more elements left */
4310 }
4312 /*
4313 * generate_subscripts_nodir
4314 * Implements the 2-argument version of generate_subscripts
4315 */
4316 Datum
4318 {
4319 /* just call the other one -- it can handle both cases */
4321 }
4323 /*
4324 * array_fill_with_lower_bounds
4325 * Create and fill array with defined lower bounds.
4326 */
4327 Datum
4329 {
4333 Oid elmtype;
4334 Datum value;
4346 {
4349 }
4350 else
4351 {
4354 }
4362 }
4364 /*
4365 * array_fill
4366 * Create and fill array with default lower bounds.
4367 */
4368 Datum
4370 {
4373 Oid elmtype;
4374 Datum value;
4385 {
4388 }
4389 else
4390 {
4393 }
4401 }
4406 {
4418 }
4423 FunctionCallInfo fcinfo)
4424 {
4431 int16 elmlen;
4436 /*
4437 * Params checks
4438 */
4470 {
4495 }
4496 else
4497 {
4504 }
4506 /* fast track for empty array */
4512 /*
4513 * We arrange to look up info about element type only once per series of
4514 * calls, assuming the element type doesn't change underneath us.
4515 */
4518 {
4523 }
4526 {
4527 /* Get info about element type */
4533 }
4539 /* compute required space */
4541 {
4547 /* make sure data is not toasted */
4557 /* check for overflow of multiplication or total request */
4565 /*
4566 * This addition can't overflow, but it might cause us to go past
4567 * MaxAllocSize. We leave it to palloc to complain in that case.
4568 */
4577 }
4578 else
4579 {
4589 /* create_array_envelope already zeroed the bitmap, so we're done */
4590 }
4593 }