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

 *

 * execJunk.c

 *    Junk attribute support stuff....

 *

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

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

 *

 *

 * IDENTIFICATION

 *    src/backend/executor/execJunk.c

 *

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

 */

#include "postgres.h"

#include "executor/executor.h"

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

 *    XXX this stuff should be rewritten to take advantage

 *      of ExecProject() and the ProjectionInfo node.

 *      -cim 6/3/91

 *

 * An attribute of a tuple living inside the executor, can be

 * either a normal attribute or a "junk" attribute. "junk" attributes

 * never make it out of the executor, i.e. they are never printed,

 * returned or stored on disk. Their only purpose in life is to

 * store some information useful only to the executor, mainly the values

 * of system attributes like "ctid", or sort key columns that are not to

 * be output.

 *

 * The general idea is the following: A target list consists of a list of

 * TargetEntry nodes containing expressions. Each TargetEntry has a field

 * called 'resjunk'. If the value of this field is true then the

 * corresponding attribute is a "junk" attribute.

 *

 * When we initialize a plan we call ExecInitJunkFilter to create a filter.

 *

 * We then execute the plan, treating the resjunk attributes like any others.

 *

 * Finally, when at the top level we get back a tuple, we can call

 * ExecFindJunkAttribute/ExecGetJunkAttribute to retrieve the values of the

 * junk attributes we are interested in, and ExecFilterJunk to remove all the

 * junk attributes from a tuple.  This new "clean" tuple is then printed,

 * inserted, or updated.

 *

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

 */

/*

 * ExecInitJunkFilter

 *

 * Initialize the Junk filter.

 *

 * The source targetlist is passed in.  The output tuple descriptor is

 * built from the non-junk tlist entries.

 * An optional resultSlot can be passed as well; otherwise, we create one.

 */

JunkFilter *

ExecInitJunkFilter(List *targetList, TupleTableSlot *slot)

{

  JunkFilter *junkfilter;

  TupleDesc cleanTupType;

  int     cleanLength;

  AttrNumber *cleanMap;

  /*

   * Compute the tuple descriptor for the cleaned tuple.

   */

  cleanTupType = ExecCleanTypeFromTL(targetList);

  /*

   * Use the given slot, or make a new slot if we weren't given one.

   */

  if (slot)

    ExecSetSlotDescriptor(slot, cleanTupType);

  else

    slot = MakeSingleTupleTableSlot(cleanTupType, &TTSOpsVirtual);

  /*

   * Now calculate the mapping between the original tuple's attributes and

   * the "clean" tuple's attributes.

   *

   * The "map" is an array of "cleanLength" attribute numbers, i.e. one

   * entry for every attribute of the "clean" tuple. The value of this entry

   * is the attribute number of the corresponding attribute of the

   * "original" tuple.  (Zero indicates a NULL output attribute, but we do

   * not use that feature in this routine.)

   */

  cleanLength = cleanTupType->natts;

  if (cleanLength > 0)

  {

    AttrNumber  cleanResno;

    ListCell   *t;

    cleanMap = (AttrNumber *) palloc(cleanLength * sizeof(AttrNumber));

    cleanResno = 0;

    foreach(t, targetList)

    {

      TargetEntry *tle = lfirst(t);

      if (!tle->resjunk)

      {

        cleanMap[cleanResno] = tle->resno;

        cleanResno++;

      }

    }

    Assert(cleanResno == cleanLength);

  }

  else

    cleanMap = NULL;

  /*

   * Finally create and initialize the JunkFilter struct.

   */

  junkfilter = makeNode(JunkFilter);

  junkfilter->jf_targetList = targetList;

  junkfilter->jf_cleanTupType = cleanTupType;

  junkfilter->jf_cleanMap = cleanMap;

  junkfilter->jf_resultSlot = slot;

  return junkfilter;

}

/*

 * ExecInitJunkFilterConversion

 *

 * Initialize a JunkFilter for rowtype conversions.

 *

 * Here, we are given the target "clean" tuple descriptor rather than

 * inferring it from the targetlist.  The target descriptor can contain

 * deleted columns.  It is assumed that the caller has checked that the

 * non-deleted columns match up with the non-junk columns of the targetlist.

 */

JunkFilter *

ExecInitJunkFilterConversion(List *targetList,

               TupleDesc cleanTupType,

               TupleTableSlot *slot)

{

  JunkFilter *junkfilter;

  int     cleanLength;

  AttrNumber *cleanMap;

  ListCell   *t;

  int     i;

  /*

   * Use the given slot, or make a new slot if we weren't given one.

   */

  if (slot)

    ExecSetSlotDescriptor(slot, cleanTupType);

  else

    slot = MakeSingleTupleTableSlot(cleanTupType, &TTSOpsVirtual);

  /*

   * Calculate the mapping between the original tuple's attributes and the

   * "clean" tuple's attributes.

   *

   * The "map" is an array of "cleanLength" attribute numbers, i.e. one

   * entry for every attribute of the "clean" tuple. The value of this entry

   * is the attribute number of the corresponding attribute of the

   * "original" tuple.  We store zero for any deleted attributes, marking

   * that a NULL is needed in the output tuple.

   */

  cleanLength = cleanTupType->natts;

  if (cleanLength > 0)

  {

    cleanMap = (AttrNumber *) palloc0(cleanLength * sizeof(AttrNumber));

    t = list_head(targetList);

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

    {

      if (TupleDescCompactAttr(cleanTupType, i)->attisdropped)

        continue;   /* map entry is already zero */

      for (;;)

      {

        TargetEntry *tle = lfirst(t);

        t = lnext(targetList, t);

        if (!tle->resjunk)

        {

          cleanMap[i] = tle->resno;

          break;

        }

      }

    }

  }

  else

    cleanMap = NULL;

  /*

   * Finally create and initialize the JunkFilter struct.

   */

  junkfilter = makeNode(JunkFilter);

  junkfilter->jf_targetList = targetList;

  junkfilter->jf_cleanTupType = cleanTupType;

  junkfilter->jf_cleanMap = cleanMap;

  junkfilter->jf_resultSlot = slot;

  return junkfilter;

}

/*

 * ExecFindJunkAttribute

 *

 * Locate the specified junk attribute in the junk filter's targetlist,

 * and return its resno.  Returns InvalidAttrNumber if not found.

 */

AttrNumber

ExecFindJunkAttribute(JunkFilter *junkfilter, const char *attrName)

{

  return ExecFindJunkAttributeInTlist(junkfilter->jf_targetList, attrName);

}

/*

 * ExecFindJunkAttributeInTlist

 *

 * Find a junk attribute given a subplan's targetlist (not necessarily

 * part of a JunkFilter).

 */

AttrNumber

ExecFindJunkAttributeInTlist(List *targetlist, const char *attrName)

{

  ListCell   *t;

  foreach(t, targetlist)

  {

    TargetEntry *tle = lfirst(t);

    if (tle->resjunk && tle->resname &&

      (strcmp(tle->resname, attrName) == 0))

    {

      /* We found it ! */

      return tle->resno;

    }

  }

  return InvalidAttrNumber;

}

/*

 * ExecFilterJunk

 *

 * Construct and return a slot with all the junk attributes removed.

 */

TupleTableSlot *

ExecFilterJunk(JunkFilter *junkfilter, TupleTableSlot *slot)

{

  TupleTableSlot *resultSlot;

  AttrNumber *cleanMap;

  TupleDesc cleanTupType;

  int     cleanLength;

  int     i;

  Datum    *values;

  bool     *isnull;

  Datum    *old_values;

  bool     *old_isnull;

  /*

   * Extract all the values of the old tuple.

   */

  slot_getallattrs(slot);

  old_values = slot->tts_values;

  old_isnull = slot->tts_isnull;

  /*

   * get info from the junk filter

   */

  cleanTupType = junkfilter->jf_cleanTupType;

  cleanLength = cleanTupType->natts;

  cleanMap = junkfilter->jf_cleanMap;

  resultSlot = junkfilter->jf_resultSlot;

  /*

   * Prepare to build a virtual result tuple.

   */

  ExecClearTuple(resultSlot);

  values = resultSlot->tts_values;

  isnull = resultSlot->tts_isnull;

  /*

   * Transpose data into proper fields of the new tuple.

   */

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

  {

    int     j = cleanMap[i];

    if (j == 0)

    {

      values[i] = (Datum) 0;

      isnull[i] = true;

    }

    else

    {

      values[i] = old_values[j - 1];

      isnull[i] = old_isnull[j - 1];

    }

  }

  /*

   * And return the virtual tuple.

   */

  return ExecStoreVirtualTuple(resultSlot);

}