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

 *

 * enum.c

 *    I/O functions, operators, aggregates etc for enum types

 *

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

 *

 *

 * IDENTIFICATION

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

 *

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

 */

#include "postgres.h"

#include "access/genam.h"

#include "access/htup_details.h"

#include "access/table.h"

#include "catalog/pg_enum.h"

#include "libpq/pqformat.h"

#include "storage/procarray.h"

#include "utils/array.h"

#include "utils/builtins.h"

#include "utils/fmgroids.h"

#include "utils/syscache.h"

#include "utils/typcache.h"

static Oid  enum_endpoint(Oid enumtypoid, ScanDirection direction);

static ArrayType *enum_range_internal(Oid enumtypoid, Oid lower, Oid upper);

/*

 * Disallow use of an uncommitted pg_enum tuple.

 *

 * We need to make sure that uncommitted enum values don't get into indexes.

 * If they did, and if we then rolled back the pg_enum addition, we'd have

 * broken the index because value comparisons will not work reliably without

 * an underlying pg_enum entry.  (Note that removal of the heap entry

 * containing an enum value is not sufficient to ensure that it doesn't appear

 * in upper levels of indexes.)  To do this we prevent an uncommitted row from

 * being used for any SQL-level purpose.  This is stronger than necessary,

 * since the value might not be getting inserted into a table or there might

 * be no index on its column, but it's easy to enforce centrally.

 *

 * However, it's okay to allow use of uncommitted values belonging to enum

 * types that were themselves created in the same transaction, because then

 * any such index would also be new and would go away altogether on rollback.

 * We don't implement that fully right now, but we do allow free use of enum

 * values created during CREATE TYPE AS ENUM, which are surely of the same

 * lifespan as the enum type.  (This case is required by "pg_restore -1".)

 * Values added by ALTER TYPE ADD VALUE are also allowed if the enum type

 * is known to have been created earlier in the same transaction.  (Note that

 * we have to track that explicitly; comparing tuple xmins is insufficient,

 * because the type tuple might have been updated in the current transaction.

 * Subtransactions also create hazards to be accounted for; currently,

 * pg_enum.c only handles ADD VALUE at the outermost transaction level.)

 *

 * This function needs to be called (directly or indirectly) in any of the

 * functions below that could return an enum value to SQL operations.

 */

static void

check_safe_enum_use(HeapTuple enumval_tup)

{

  TransactionId xmin;

  Form_pg_enum en = (Form_pg_enum) GETSTRUCT(enumval_tup);

  /*

   * If the row is hinted as committed, it's surely safe.  This provides a

   * fast path for all normal use-cases.

   */

  if (HeapTupleHeaderXminCommitted(enumval_tup->t_data))

    return;

  /*

   * Usually, a row would get hinted as committed when it's read or loaded

   * into syscache; but just in case not, let's check the xmin directly.

   */

  xmin = HeapTupleHeaderGetXmin(enumval_tup->t_data);

  if (!TransactionIdIsInProgress(xmin) &&

    TransactionIdDidCommit(xmin))

    return;

  /*

   * Check if the enum value is listed as uncommitted.  If not, it's safe,

   * because it can't be shorter-lived than its owning type.  (This'd also

   * be false for values made by other transactions; but the previous tests

   * should have handled all of those.)

   */

  if (!EnumUncommitted(en->oid))

    return;

  /*

   * There might well be other tests we could do here to narrow down the

   * unsafe conditions, but for now just raise an exception.

   */

  ereport(ERROR,

      (errcode(ERRCODE_UNSAFE_NEW_ENUM_VALUE_USAGE),

       errmsg("unsafe use of new value \"%s\" of enum type %s",

          NameStr(en->enumlabel),

          format_type_be(en->enumtypid)),

       errhint("New enum values must be committed before they can be used.")));

}

/* Basic I/O support */

Datum

enum_in(PG_FUNCTION_ARGS)

{

  char     *name = PG_GETARG_CSTRING(0);

  Oid     enumtypoid = PG_GETARG_OID(1);

  Node     *escontext = fcinfo->context;

  Oid     enumoid;

  HeapTuple tup;

  /* must check length to prevent Assert failure within SearchSysCache */

  if (strlen(name) >= NAMEDATALEN)

    ereturn(escontext, (Datum) 0,

        (errcode(ERRCODE_INVALID_TEXT_REPRESENTATION),

         errmsg("invalid input value for enum %s: \"%s\"",

            format_type_be(enumtypoid),

            name)));

  tup = SearchSysCache2(ENUMTYPOIDNAME,

              ObjectIdGetDatum(enumtypoid),

              CStringGetDatum(name));

  if (!HeapTupleIsValid(tup))

    ereturn(escontext, (Datum) 0,

        (errcode(ERRCODE_INVALID_TEXT_REPRESENTATION),

         errmsg("invalid input value for enum %s: \"%s\"",

            format_type_be(enumtypoid),

            name)));

  /*

   * Check it's safe to use in SQL.  Perhaps we should take the trouble to

   * report "unsafe use" softly; but it's unclear that it's worth the

   * trouble, or indeed that that is a legitimate bad-input case at all

   * rather than an implementation shortcoming.

   */

  check_safe_enum_use(tup);

  /*

   * This comes from pg_enum.oid and stores system oids in user tables. This

   * oid must be preserved by binary upgrades.

   */

  enumoid = ((Form_pg_enum) GETSTRUCT(tup))->oid;

  ReleaseSysCache(tup);

  PG_RETURN_OID(enumoid);

}

Datum

enum_out(PG_FUNCTION_ARGS)

{

  Oid     enumval = PG_GETARG_OID(0);

  char     *result;

  HeapTuple tup;

  Form_pg_enum en;

  tup = SearchSysCache1(ENUMOID, ObjectIdGetDatum(enumval));

  if (!HeapTupleIsValid(tup))

    ereport(ERROR,

        (errcode(ERRCODE_INVALID_BINARY_REPRESENTATION),

         errmsg("invalid internal value for enum: %u",

            enumval)));

  en = (Form_pg_enum) GETSTRUCT(tup);

  result = pstrdup(NameStr(en->enumlabel));

  ReleaseSysCache(tup);

  PG_RETURN_CSTRING(result);

}

/* Binary I/O support */

Datum

enum_recv(PG_FUNCTION_ARGS)

{

  StringInfo  buf = (StringInfo) PG_GETARG_POINTER(0);

  Oid     enumtypoid = PG_GETARG_OID(1);

  Oid     enumoid;

  HeapTuple tup;

  char     *name;

  int     nbytes;

  name = pq_getmsgtext(buf, buf->len - buf->cursor, &nbytes);

  /* must check length to prevent Assert failure within SearchSysCache */

  if (strlen(name) >= NAMEDATALEN)

    ereport(ERROR,

        (errcode(ERRCODE_INVALID_TEXT_REPRESENTATION),

         errmsg("invalid input value for enum %s: \"%s\"",

            format_type_be(enumtypoid),

            name)));

  tup = SearchSysCache2(ENUMTYPOIDNAME,

              ObjectIdGetDatum(enumtypoid),

              CStringGetDatum(name));

  if (!HeapTupleIsValid(tup))

    ereport(ERROR,

        (errcode(ERRCODE_INVALID_TEXT_REPRESENTATION),

         errmsg("invalid input value for enum %s: \"%s\"",

            format_type_be(enumtypoid),

            name)));

  /* check it's safe to use in SQL */

  check_safe_enum_use(tup);

  enumoid = ((Form_pg_enum) GETSTRUCT(tup))->oid;

  ReleaseSysCache(tup);

  pfree(name);

  PG_RETURN_OID(enumoid);

}

Datum

enum_send(PG_FUNCTION_ARGS)

{

  Oid     enumval = PG_GETARG_OID(0);

  StringInfoData buf;

  HeapTuple tup;

  Form_pg_enum en;

  tup = SearchSysCache1(ENUMOID, ObjectIdGetDatum(enumval));

  if (!HeapTupleIsValid(tup))

    ereport(ERROR,

        (errcode(ERRCODE_INVALID_BINARY_REPRESENTATION),

         errmsg("invalid internal value for enum: %u",

            enumval)));

  en = (Form_pg_enum) GETSTRUCT(tup);

  pq_begintypsend(&buf);

  pq_sendtext(&buf, NameStr(en->enumlabel), strlen(NameStr(en->enumlabel)));

  ReleaseSysCache(tup);

  PG_RETURN_BYTEA_P(pq_endtypsend(&buf));

}

/* Comparison functions and related */

/*

 * enum_cmp_internal is the common engine for all the visible comparison

 * functions, except for enum_eq and enum_ne which can just check for OID

 * equality directly.

 */

static int

enum_cmp_internal(Oid arg1, Oid arg2, FunctionCallInfo fcinfo)

{

  TypeCacheEntry *tcache;

  /*

   * We don't need the typcache except in the hopefully-uncommon case that

   * one or both Oids are odd.  This means that cursory testing of code that

   * fails to pass flinfo to an enum comparison function might not disclose

   * the oversight.  To make such errors more obvious, Assert that we have a

   * place to cache even when we take a fast-path exit.

   */

  Assert(fcinfo->flinfo != NULL);

  /* Equal OIDs are equal no matter what */

  if (arg1 == arg2)

    return 0;

  /* Fast path: even-numbered Oids are known to compare correctly */

  if ((arg1 & 1) == 0 && (arg2 & 1) == 0)

  {

    if (arg1 < arg2)

      return -1;

    else

      return 1;

  }

  /* Locate the typcache entry for the enum type */

  tcache = (TypeCacheEntry *) fcinfo->flinfo->fn_extra;

  if (tcache == NULL)

  {

    HeapTuple enum_tup;

    Form_pg_enum en;

    Oid     typeoid;

    /* Get the OID of the enum type containing arg1 */

    enum_tup = SearchSysCache1(ENUMOID, ObjectIdGetDatum(arg1));

    if (!HeapTupleIsValid(enum_tup))

      ereport(ERROR,

          (errcode(ERRCODE_INVALID_BINARY_REPRESENTATION),

           errmsg("invalid internal value for enum: %u",

              arg1)));

    en = (Form_pg_enum) GETSTRUCT(enum_tup);

    typeoid = en->enumtypid;

    ReleaseSysCache(enum_tup);

    /* Now locate and remember the typcache entry */

    tcache = lookup_type_cache(typeoid, 0);

    fcinfo->flinfo->fn_extra = tcache;

  }

  /* The remaining comparison logic is in typcache.c */

  return compare_values_of_enum(tcache, arg1, arg2);

}

Datum

enum_lt(PG_FUNCTION_ARGS)

{

  Oid     a = PG_GETARG_OID(0);

  Oid     b = PG_GETARG_OID(1);

  PG_RETURN_BOOL(enum_cmp_internal(a, b, fcinfo) < 0);

}

Datum

enum_le(PG_FUNCTION_ARGS)

{

  Oid     a = PG_GETARG_OID(0);

  Oid     b = PG_GETARG_OID(1);

  PG_RETURN_BOOL(enum_cmp_internal(a, b, fcinfo) <= 0);

}

Datum

enum_eq(PG_FUNCTION_ARGS)

{

  Oid     a = PG_GETARG_OID(0);

  Oid     b = PG_GETARG_OID(1);

  PG_RETURN_BOOL(a == b);

}

Datum

enum_ne(PG_FUNCTION_ARGS)

{

  Oid     a = PG_GETARG_OID(0);

  Oid     b = PG_GETARG_OID(1);

  PG_RETURN_BOOL(a != b);

}

Datum

enum_ge(PG_FUNCTION_ARGS)

{

  Oid     a = PG_GETARG_OID(0);

  Oid     b = PG_GETARG_OID(1);

  PG_RETURN_BOOL(enum_cmp_internal(a, b, fcinfo) >= 0);

}

Datum

enum_gt(PG_FUNCTION_ARGS)

{

  Oid     a = PG_GETARG_OID(0);

  Oid     b = PG_GETARG_OID(1);

  PG_RETURN_BOOL(enum_cmp_internal(a, b, fcinfo) > 0);

}

Datum

enum_smaller(PG_FUNCTION_ARGS)

{

  Oid     a = PG_GETARG_OID(0);

  Oid     b = PG_GETARG_OID(1);

  PG_RETURN_OID(enum_cmp_internal(a, b, fcinfo) < 0 ? a : b);

}

Datum

enum_larger(PG_FUNCTION_ARGS)

{

  Oid     a = PG_GETARG_OID(0);

  Oid     b = PG_GETARG_OID(1);

  PG_RETURN_OID(enum_cmp_internal(a, b, fcinfo) > 0 ? a : b);

}

Datum

enum_cmp(PG_FUNCTION_ARGS)

{

  Oid     a = PG_GETARG_OID(0);

  Oid     b = PG_GETARG_OID(1);

  PG_RETURN_INT32(enum_cmp_internal(a, b, fcinfo));

}

/* Enum programming support functions */

/*

 * enum_endpoint: common code for enum_first/enum_last

 */

static Oid

enum_endpoint(Oid enumtypoid, ScanDirection direction)

{

  Relation  enum_rel;

  Relation  enum_idx;

  SysScanDesc enum_scan;

  HeapTuple enum_tuple;

  ScanKeyData skey;

  Oid     minmax;

  /*

   * Find the first/last enum member using pg_enum_typid_sortorder_index.

   * Note we must not use the syscache.  See comments for RenumberEnumType

   * in catalog/pg_enum.c for more info.

   */

  ScanKeyInit(&skey,

        Anum_pg_enum_enumtypid,

        BTEqualStrategyNumber, F_OIDEQ,

        ObjectIdGetDatum(enumtypoid));

  enum_rel = table_open(EnumRelationId, AccessShareLock);

  enum_idx = index_open(EnumTypIdSortOrderIndexId, AccessShareLock);

  enum_scan = systable_beginscan_ordered(enum_rel, enum_idx, NULL,

                       1, &skey);

  enum_tuple = systable_getnext_ordered(enum_scan, direction);

  if (HeapTupleIsValid(enum_tuple))

  {

    /* check it's safe to use in SQL */

    check_safe_enum_use(enum_tuple);

    minmax = ((Form_pg_enum) GETSTRUCT(enum_tuple))->oid;

  }

  else

  {

    /* should only happen with an empty enum */

    minmax = InvalidOid;

  }

  systable_endscan_ordered(enum_scan);

  index_close(enum_idx, AccessShareLock);

  table_close(enum_rel, AccessShareLock);

  return minmax;

}

Datum

enum_first(PG_FUNCTION_ARGS)

{

  Oid     enumtypoid;

  Oid     min;

  /*

   * We rely on being able to get the specific enum type from the calling

   * expression tree.  Notice that the actual value of the argument isn't

   * examined at all; in particular it might be NULL.

   */

  enumtypoid = get_fn_expr_argtype(fcinfo->flinfo, 0);

  if (enumtypoid == InvalidOid)

    ereport(ERROR,

        (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),

         errmsg("could not determine actual enum type")));

  /* Get the OID using the index */

  min = enum_endpoint(enumtypoid, ForwardScanDirection);

  if (!OidIsValid(min))

    ereport(ERROR,

        (errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),

         errmsg("enum %s contains no values",

            format_type_be(enumtypoid))));

  PG_RETURN_OID(min);

}

Datum

enum_last(PG_FUNCTION_ARGS)

{

  Oid     enumtypoid;

  Oid     max;

  /*

   * We rely on being able to get the specific enum type from the calling

   * expression tree.  Notice that the actual value of the argument isn't

   * examined at all; in particular it might be NULL.

   */

  enumtypoid = get_fn_expr_argtype(fcinfo->flinfo, 0);

  if (enumtypoid == InvalidOid)

    ereport(ERROR,

        (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),

         errmsg("could not determine actual enum type")));

  /* Get the OID using the index */

  max = enum_endpoint(enumtypoid, BackwardScanDirection);

  if (!OidIsValid(max))

    ereport(ERROR,

        (errcode(ERRCODE_OBJECT_NOT_IN_PREREQUISITE_STATE),

         errmsg("enum %s contains no values",

            format_type_be(enumtypoid))));

  PG_RETURN_OID(max);

}

/* 2-argument variant of enum_range */

Datum

enum_range_bounds(PG_FUNCTION_ARGS)

{

  Oid     lower;

  Oid     upper;

  Oid     enumtypoid;

  if (PG_ARGISNULL(0))

    lower = InvalidOid;

  else

    lower = PG_GETARG_OID(0);

  if (PG_ARGISNULL(1))

    upper = InvalidOid;

  else

    upper = PG_GETARG_OID(1);

  /*

   * We rely on being able to get the specific enum type from the calling

   * expression tree.  The generic type mechanism should have ensured that

   * both are of the same type.

   */

  enumtypoid = get_fn_expr_argtype(fcinfo->flinfo, 0);

  if (enumtypoid == InvalidOid)

    ereport(ERROR,

        (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),

         errmsg("could not determine actual enum type")));

  PG_RETURN_ARRAYTYPE_P(enum_range_internal(enumtypoid, lower, upper));

}

/* 1-argument variant of enum_range */

Datum

enum_range_all(PG_FUNCTION_ARGS)

{

  Oid     enumtypoid;

  /*

   * We rely on being able to get the specific enum type from the calling

   * expression tree.  Notice that the actual value of the argument isn't

   * examined at all; in particular it might be NULL.

   */

  enumtypoid = get_fn_expr_argtype(fcinfo->flinfo, 0);

  if (enumtypoid == InvalidOid)

    ereport(ERROR,

        (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),

         errmsg("could not determine actual enum type")));

  PG_RETURN_ARRAYTYPE_P(enum_range_internal(enumtypoid,

                        InvalidOid, InvalidOid));

}

static ArrayType *

enum_range_internal(Oid enumtypoid, Oid lower, Oid upper)

{

  ArrayType  *result;

  Relation  enum_rel;

  Relation  enum_idx;

  SysScanDesc enum_scan;

  HeapTuple enum_tuple;

  ScanKeyData skey;

  Datum    *elems;

  int     max,

        cnt;

  bool    left_found;

  /*

   * Scan the enum members in order using pg_enum_typid_sortorder_index.

   * Note we must not use the syscache.  See comments for RenumberEnumType

   * in catalog/pg_enum.c for more info.

   */

  ScanKeyInit(&skey,

        Anum_pg_enum_enumtypid,

        BTEqualStrategyNumber, F_OIDEQ,

        ObjectIdGetDatum(enumtypoid));

  enum_rel = table_open(EnumRelationId, AccessShareLock);

  enum_idx = index_open(EnumTypIdSortOrderIndexId, AccessShareLock);

  enum_scan = systable_beginscan_ordered(enum_rel, enum_idx, NULL, 1, &skey);

  max = 64;

  elems = (Datum *) palloc(max * sizeof(Datum));

  cnt = 0;

  left_found = !OidIsValid(lower);

  while (HeapTupleIsValid(enum_tuple = systable_getnext_ordered(enum_scan, ForwardScanDirection)))

  {

    Oid     enum_oid = ((Form_pg_enum) GETSTRUCT(enum_tuple))->oid;

    if (!left_found && lower == enum_oid)

      left_found = true;

    if (left_found)

    {

      /* check it's safe to use in SQL */

      check_safe_enum_use(enum_tuple);

      if (cnt >= max)

      {

        max *= 2;

        elems = (Datum *) repalloc(elems, max * sizeof(Datum));

      }

      elems[cnt++] = ObjectIdGetDatum(enum_oid);

    }

    if (OidIsValid(upper) && upper == enum_oid)

      break;

  }

  systable_endscan_ordered(enum_scan);

  index_close(enum_idx, AccessShareLock);

  table_close(enum_rel, AccessShareLock);

  /* and build the result array */

  /* note this hardwires some details about the representation of Oid */

  result = construct_array(elems, cnt, enumtypoid,

               sizeof(Oid), true, TYPALIGN_INT);

  pfree(elems);

  return result;

}