/*-------------------------------------------------------------------------

 *

 * array_expanded.c

 *    Basic functions for manipulating expanded arrays.

 *

 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group

 * Portions Copyright (c) 1994, Regents of the University of California

 *

 *

 * IDENTIFICATION

 *    src/backend/utils/adt/array_expanded.c

 *

 *-------------------------------------------------------------------------

 */

#include "postgres.h"

#include "access/tupmacs.h"

#include "utils/array.h"

#include "utils/lsyscache.h"

#include "utils/memutils.h"

/* "Methods" required for an expanded object */

static Size EA_get_flat_size(ExpandedObjectHeader *eohptr);

static void EA_flatten_into(ExpandedObjectHeader *eohptr,

              void *result, Size allocated_size);

static const ExpandedObjectMethods EA_methods =

{

  EA_get_flat_size,

  EA_flatten_into

};

/* Other local functions */

static void copy_byval_expanded_array(ExpandedArrayHeader *eah,

                    ExpandedArrayHeader *oldeah);

/*

 * expand_array: convert an array Datum into an expanded array

 *

 * The expanded object will be a child of parentcontext.

 *

 * Some callers can provide cache space to avoid repeated lookups of element

 * type data across calls; if so, pass a metacache pointer, making sure that

 * metacache->element_type is initialized to InvalidOid before first call.

 * If no cross-call caching is required, pass NULL for metacache.

 */

Datum

expand_array(Datum arraydatum, MemoryContext parentcontext,

       ArrayMetaState *metacache)

{

  ArrayType  *array;

  ExpandedArrayHeader *eah;

  MemoryContext objcxt;

  MemoryContext oldcxt;

  ArrayMetaState fakecache;

  /*

   * Allocate private context for expanded object.  We start by assuming

   * that the array won't be very large; but if it does grow a lot, don't

   * constrain aset.c's large-context behavior.

   */

  objcxt = AllocSetContextCreate(parentcontext,

                   "expanded array",

                   ALLOCSET_START_SMALL_SIZES);

  /* Set up expanded array header */

  eah = (ExpandedArrayHeader *)

    MemoryContextAlloc(objcxt, sizeof(ExpandedArrayHeader));

  EOH_init_header(&eah->hdr, &EA_methods, objcxt);

  eah->ea_magic = EA_MAGIC;

  /* If the source is an expanded array, we may be able to optimize */

  if (VARATT_IS_EXTERNAL_EXPANDED(DatumGetPointer(arraydatum)))

  {

    ExpandedArrayHeader *oldeah = (ExpandedArrayHeader *) DatumGetEOHP(arraydatum);

    Assert(oldeah->ea_magic == EA_MAGIC);

    /*

     * Update caller's cache if provided; we don't need it this time, but

     * next call might be for a non-expanded source array.  Furthermore,

     * if the caller didn't provide a cache area, use some local storage

     * to cache anyway, thereby avoiding a catalog lookup in the case

     * where we fall through to the flat-copy code path.

     */

    if (metacache == NULL)

      metacache = &fakecache;

    metacache->element_type = oldeah->element_type;

    metacache->typlen = oldeah->typlen;

    metacache->typbyval = oldeah->typbyval;

    metacache->typalign = oldeah->typalign;

    /*

     * If element type is pass-by-value and we have a Datum-array

     * representation, just copy the source's metadata and Datum/isnull

     * arrays.  The original flat array, if present at all, adds no

     * additional information so we need not copy it.

     */

    if (oldeah->typbyval && oldeah->dvalues != NULL)

    {

      copy_byval_expanded_array(eah, oldeah);

      /* return a R/W pointer to the expanded array */

      return EOHPGetRWDatum(&eah->hdr);

    }

    /*

     * Otherwise, either we have only a flat representation or the

     * elements are pass-by-reference.  In either case, the best thing

     * seems to be to copy the source as a flat representation and then

     * deconstruct that later if necessary.  For the pass-by-ref case, we

     * could perhaps save some cycles with custom code that generates the

     * deconstructed representation in parallel with copying the values,

     * but it would be a lot of extra code for fairly marginal gain.  So,

     * fall through into the flat-source code path.

     */

  }

  /*

   * Detoast and copy source array into private context, as a flat array.

   *

   * Note that this coding risks leaking some memory in the private context

   * if we have to fetch data from a TOAST table; however, experimentation

   * says that the leak is minimal.  Doing it this way saves a copy step,

   * which seems worthwhile, especially if the array is large enough to need

   * external storage.

   */

  oldcxt = MemoryContextSwitchTo(objcxt);

  array = DatumGetArrayTypePCopy(arraydatum);

  MemoryContextSwitchTo(oldcxt);

  eah->ndims = ARR_NDIM(array);

  /* note these pointers point into the fvalue header! */

  eah->dims = ARR_DIMS(array);

  eah->lbound = ARR_LBOUND(array);

  /* Save array's element-type data for possible use later */

  eah->element_type = ARR_ELEMTYPE(array);

  if (metacache && metacache->element_type == eah->element_type)

  {

    /* We have a valid cache of representational data */

    eah->typlen = metacache->typlen;

    eah->typbyval = metacache->typbyval;

    eah->typalign = metacache->typalign;

  }

  else

  {

    /* No, so look it up */

    get_typlenbyvalalign(eah->element_type,

               &eah->typlen,

               &eah->typbyval,

               &eah->typalign);

    /* Update cache if provided */

    if (metacache)

    {

      metacache->element_type = eah->element_type;

      metacache->typlen = eah->typlen;

      metacache->typbyval = eah->typbyval;

      metacache->typalign = eah->typalign;

    }

  }

  /* we don't make a deconstructed representation now */

  eah->dvalues = NULL;

  eah->dnulls = NULL;

  eah->dvalueslen = 0;

  eah->nelems = 0;

  eah->flat_size = 0;

  /* remember we have a flat representation */

  eah->fvalue = array;

  eah->fstartptr = ARR_DATA_PTR(array);

  eah->fendptr = ((char *) array) + ARR_SIZE(array);

  /* return a R/W pointer to the expanded array */

  return EOHPGetRWDatum(&eah->hdr);

}

/*

 * helper for expand_array(): copy pass-by-value Datum-array representation

 */

static void

copy_byval_expanded_array(ExpandedArrayHeader *eah,

              ExpandedArrayHeader *oldeah)

{

  MemoryContext objcxt = eah->hdr.eoh_context;

  int     ndims = oldeah->ndims;

  int     dvalueslen = oldeah->dvalueslen;

  /* Copy array dimensionality information */

  eah->ndims = ndims;

  /* We can alloc both dimensionality arrays with one palloc */

  eah->dims = (int *) MemoryContextAlloc(objcxt, ndims * 2 * sizeof(int));

  eah->lbound = eah->dims + ndims;

  /* .. but don't assume the source's arrays are contiguous */

  memcpy(eah->dims, oldeah->dims, ndims * sizeof(int));

  memcpy(eah->lbound, oldeah->lbound, ndims * sizeof(int));

  /* Copy element-type data */

  eah->element_type = oldeah->element_type;

  eah->typlen = oldeah->typlen;

  eah->typbyval = oldeah->typbyval;

  eah->typalign = oldeah->typalign;

  /* Copy the deconstructed representation */

  eah->dvalues = (Datum *) MemoryContextAlloc(objcxt,

                        dvalueslen * sizeof(Datum));

  memcpy(eah->dvalues, oldeah->dvalues, dvalueslen * sizeof(Datum));

  if (oldeah->dnulls)

  {

    eah->dnulls = (bool *) MemoryContextAlloc(objcxt,

                          dvalueslen * sizeof(bool));

    memcpy(eah->dnulls, oldeah->dnulls, dvalueslen * sizeof(bool));

  }

  else

    eah->dnulls = NULL;

  eah->dvalueslen = dvalueslen;

  eah->nelems = oldeah->nelems;

  eah->flat_size = oldeah->flat_size;

  /* we don't make a flat representation */

  eah->fvalue = NULL;

  eah->fstartptr = NULL;

  eah->fendptr = NULL;

}

/*

 * get_flat_size method for expanded arrays

 */

static Size

EA_get_flat_size(ExpandedObjectHeader *eohptr)

{

  ExpandedArrayHeader *eah = (ExpandedArrayHeader *) eohptr;

  int     nelems;

  int     ndims;

  Datum    *dvalues;

  bool     *dnulls;

  Size    nbytes;

  int     i;

  Assert(eah->ea_magic == EA_MAGIC);

  /* Easy if we have a valid flattened value */

  if (eah->fvalue)

    return ARR_SIZE(eah->fvalue);

  /* If we have a cached size value, believe that */

  if (eah->flat_size)

    return eah->flat_size;

  /*

   * Compute space needed by examining dvalues/dnulls.  Note that the result

   * array will have a nulls bitmap if dnulls isn't NULL, even if the array

   * doesn't actually contain any nulls now.

   */

  nelems = eah->nelems;

  ndims = eah->ndims;

  Assert(nelems == ArrayGetNItems(ndims, eah->dims));

  dvalues = eah->dvalues;

  dnulls = eah->dnulls;

  nbytes = 0;

  for (i = 0; i < nelems; i++)

  {

    if (dnulls && dnulls[i])

      continue;

    nbytes = att_addlength_datum(nbytes, eah->typlen, dvalues[i]);

    nbytes = att_align_nominal(nbytes, eah->typalign);

    /* check for overflow of total request */

    if (!AllocSizeIsValid(nbytes))

      ereport(ERROR,

          (errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED),

           errmsg("array size exceeds the maximum allowed (%d)",

              (int) MaxAllocSize)));

  }

  if (dnulls)

    nbytes += ARR_OVERHEAD_WITHNULLS(ndims, nelems);

  else

    nbytes += ARR_OVERHEAD_NONULLS(ndims);

  /* cache for next time */

  eah->flat_size = nbytes;

  return nbytes;

}

/*

 * flatten_into method for expanded arrays

 */

static void

EA_flatten_into(ExpandedObjectHeader *eohptr,

        void *result, Size allocated_size)

{

  ExpandedArrayHeader *eah = (ExpandedArrayHeader *) eohptr;

  ArrayType  *aresult = (ArrayType *) result;

  int     nelems;

  int     ndims;

  int32   dataoffset;

  Assert(eah->ea_magic == EA_MAGIC);

  /* Easy if we have a valid flattened value */

  if (eah->fvalue)

  {

    Assert(allocated_size == ARR_SIZE(eah->fvalue));

    memcpy(result, eah->fvalue, allocated_size);

    return;

  }

  /* Else allocation should match previous get_flat_size result */

  Assert(allocated_size == eah->flat_size);

  /* Fill result array from dvalues/dnulls */

  nelems = eah->nelems;

  ndims = eah->ndims;

  if (eah->dnulls)

    dataoffset = ARR_OVERHEAD_WITHNULLS(ndims, nelems);

  else

    dataoffset = 0;     /* marker for no null bitmap */

  /* We must ensure that any pad space is zero-filled */

  memset(aresult, 0, allocated_size);

  SET_VARSIZE(aresult, allocated_size);

  aresult->ndim = ndims;

  aresult->dataoffset = dataoffset;

  aresult->elemtype = eah->element_type;

  memcpy(ARR_DIMS(aresult), eah->dims, ndims * sizeof(int));

  memcpy(ARR_LBOUND(aresult), eah->lbound, ndims * sizeof(int));

  CopyArrayEls(aresult,

         eah->dvalues, eah->dnulls, nelems,

         eah->typlen, eah->typbyval, eah->typalign,

         false);

}

/*

 * Argument fetching support code

 */

/*

 * DatumGetExpandedArray: get a writable expanded array from an input argument

 *

 * Caution: if the input is a read/write pointer, this returns the input

 * argument; so callers must be sure that their changes are "safe", that is

 * they cannot leave the array in a corrupt state.

 */

ExpandedArrayHeader *

DatumGetExpandedArray(Datum d)

{

  /* If it's a writable expanded array already, just return it */

  if (VARATT_IS_EXTERNAL_EXPANDED_RW(DatumGetPointer(d)))

  {

    ExpandedArrayHeader *eah = (ExpandedArrayHeader *) DatumGetEOHP(d);

    Assert(eah->ea_magic == EA_MAGIC);

    return eah;

  }

  /* Else expand the hard way */

  d = expand_array(d, CurrentMemoryContext, NULL);

  return (ExpandedArrayHeader *) DatumGetEOHP(d);

}

/*

 * As above, when caller has the ability to cache element type info

 */

ExpandedArrayHeader *

DatumGetExpandedArrayX(Datum d, ArrayMetaState *metacache)

{

  /* If it's a writable expanded array already, just return it */

  if (VARATT_IS_EXTERNAL_EXPANDED_RW(DatumGetPointer(d)))

  {

    ExpandedArrayHeader *eah = (ExpandedArrayHeader *) DatumGetEOHP(d);

    Assert(eah->ea_magic == EA_MAGIC);

    /* Update cache if provided */

    if (metacache)

    {

      metacache->element_type = eah->element_type;

      metacache->typlen = eah->typlen;

      metacache->typbyval = eah->typbyval;

      metacache->typalign = eah->typalign;

    }

    return eah;

  }

  /* Else expand using caller's cache if any */

  d = expand_array(d, CurrentMemoryContext, metacache);

  return (ExpandedArrayHeader *) DatumGetEOHP(d);

}

/*

 * DatumGetAnyArrayP: return either an expanded array or a detoasted varlena

 * array.  The result must not be modified in-place.

 */

AnyArrayType *

DatumGetAnyArrayP(Datum d)

{

  ExpandedArrayHeader *eah;

  /*

   * If it's an expanded array (RW or RO), return the header pointer.

   */

  if (VARATT_IS_EXTERNAL_EXPANDED(DatumGetPointer(d)))

  {

    eah = (ExpandedArrayHeader *) DatumGetEOHP(d);

    Assert(eah->ea_magic == EA_MAGIC);

    return (AnyArrayType *) eah;

  }

  /* Else do regular detoasting as needed */

  return (AnyArrayType *) PG_DETOAST_DATUM(d);

}

/*

 * Create the Datum/isnull representation of an expanded array object

 * if we didn't do so previously

 */

void

deconstruct_expanded_array(ExpandedArrayHeader *eah)

{

  if (eah->dvalues == NULL)

  {

    MemoryContext oldcxt = MemoryContextSwitchTo(eah->hdr.eoh_context);

    Datum    *dvalues;

    bool     *dnulls;

    int     nelems;

    dnulls = NULL;

    deconstruct_array(eah->fvalue,

              eah->element_type,

              eah->typlen, eah->typbyval, eah->typalign,

              &dvalues,

              ARR_HASNULL(eah->fvalue) ? &dnulls : NULL,

              &nelems);

    /*

     * Update header only after successful completion of this step.  If

     * deconstruct_array fails partway through, worst consequence is some

     * leaked memory in the object's context.  If the caller fails at a

     * later point, that's fine, since the deconstructed representation is

     * valid anyhow.

     */

    eah->dvalues = dvalues;

    eah->dnulls = dnulls;

    eah->dvalueslen = eah->nelems = nelems;

    MemoryContextSwitchTo(oldcxt);

  }

}