/*-------------------------------------------------------------------------
 *
 * ts_type.h
 *	  Definitions for the tsvector and tsquery types
 *
 * Copyright (c) 1998-2024, PostgreSQL Global Development Group
 *
 * src/include/tsearch/ts_type.h
 *
 *-------------------------------------------------------------------------
 */
#ifndef _PG_TSTYPE_H_
#define _PG_TSTYPE_H_

#include "fmgr.h"
#include "utils/memutils.h"


/*
 * TSVector type.
 *
 * Structure of tsvector datatype:
 * 1) standard varlena header
 * 2) int32		size - number of lexemes (WordEntry array entries)
 * 3) Array of WordEntry - one per lexeme; must be sorted according to
 *				tsCompareString() (ie, memcmp of lexeme strings).
 *				WordEntry->pos gives the number of bytes from end of WordEntry
 *				array to start of lexeme's string, which is of length len.
 * 4) Per-lexeme data storage:
 *	  lexeme string (not null-terminated)
 *	  if haspos is true:
 *		padding byte if necessary to make the position data 2-byte aligned
 *		uint16			number of positions that follow
 *		WordEntryPos[]	positions
 *
 * The positions for each lexeme must be sorted.
 *
 * Note that while the WordEntry items must be sorted per tsCompareString(),
 * the per-lexeme data storage could be in some other order, ie the series
 * of WordEntry->pos values need not be strictly ascending.
 */

typedef struct
{
	uint32
				haspos:1,
				len:11,			/* MAX 2Kb */
				pos:20;			/* MAX 1Mb */
} WordEntry;

#define MAXSTRLEN ( (1<<11) - 1)	/* maximum value of WordEntry.len */
#define MAXSTRPOS ( (1<<20) - 1)	/* maximum value of WordEntry.pos */

extern int	compareWordEntryPos(const void *a, const void *b);

/*
 * Representation of positions (and weights) associated with a lexeme.
 *
 * WordEntryPos is equivalent to
 * typedef struct {
 *		uint16
 *			weight:2,
 *			pos:14;
 * }
 */

typedef uint16 WordEntryPos;

typedef struct
{
	uint16		npos;
	WordEntryPos pos[FLEXIBLE_ARRAY_MEMBER];
} WordEntryPosVector;

/* WordEntryPosVector with exactly 1 entry */
typedef struct
{
	uint16		npos;
	WordEntryPos pos[1];
} WordEntryPosVector1;

#define MAXNUMPOS	(256)		/* semi-arbitrary limit on npos */

/* Macros for getting/setting the fields of a WordEntryPos */
#define WEP_GETWEIGHT(x)	( (x) >> 14 )
#define WEP_GETPOS(x)		( (x) & 0x3fff )

#define WEP_SETWEIGHT(x,v)	( (x) = ( (v) << 14 ) | ( (x) & 0x3fff ) )
#define WEP_SETPOS(x,v)		( (x) = ( (x) & 0xc000 ) | ( (v) & 0x3fff ) )

#define MAXENTRYPOS (1<<14)		/* max value of WordEntryPos pos field, +1 */
/* Macro for clamping a position to what will fit in WordEntryPos pos field */
#define LIMITPOS(x) ( ( (x) >= MAXENTRYPOS ) ? (MAXENTRYPOS-1) : (x) )

/* This struct represents a complete tsvector datum */
typedef struct
{
	int32		vl_len_;		/* varlena header (do not touch directly!) */
	int32		size;			/* number of entries[] items */
	WordEntry	entries[FLEXIBLE_ARRAY_MEMBER];
	/* lexemes follow the entries[] array */
} TSVectorData;

typedef TSVectorData *TSVector;

/*
 * Calculate the size of a TSVector given the number of WordEntries and
 * the total space needed for lexeme text and positions.  NOTE: callers
 * must enforce lenstr <= MAXSTRPOS, which ensures that WordEntry.pos
 * fields will not overflow, and also protects against integer overflow here.
 * (Since we prohibit empty lexemes, nentries can't exceed lenstr.)
 */
#define DATAHDRSIZE (offsetof(TSVectorData, entries))
#define CALCDATASIZE(nentries, lenstr) (DATAHDRSIZE + (nentries) * sizeof(WordEntry) + (lenstr) )

/* pointer to start of a tsvector's WordEntry array */
#define ARRPTR(tsv)	( (tsv)->entries )

/* pointer to start of a tsvector's lexeme storage */
#define STRPTR(tsv)	( (char *) &(tsv)->entries[(tsv)->size] )

/* pointer to WordEntryPosVector for a WordEntry */
#define _POSVECPTR(tsv,we) ((WordEntryPosVector *) \
							(STRPTR(tsv) + SHORTALIGN((we)->pos + (we)->len)))
/* number of positions stored for a WordEntry */
#define POSDATALEN(tsv,we) ( (we)->haspos ? _POSVECPTR(tsv,we)->npos : 0 )
/* pointer to start of positions stored for a WordEntry */
#define POSDATAPTR(tsv,we) (_POSVECPTR(tsv,we)->pos)

/*
 * fmgr interface functions
 */

static inline TSVector
DatumGetTSVector(Datum X)
{
	return (TSVector) PG_DETOAST_DATUM(X);
}

static inline TSVector
DatumGetTSVectorCopy(Datum X)
{
	return (TSVector) PG_DETOAST_DATUM_COPY(X);
}

static inline Datum
TSVectorGetDatum(const TSVectorData *X)
{
	return PointerGetDatum(X);
}

#define PG_GETARG_TSVECTOR(n)		DatumGetTSVector(PG_GETARG_DATUM(n))
#define PG_GETARG_TSVECTOR_COPY(n)	DatumGetTSVectorCopy(PG_GETARG_DATUM(n))
#define PG_RETURN_TSVECTOR(x)		return TSVectorGetDatum(x)


/*
 * TSQuery
 *
 *
 */

typedef int8 QueryItemType;

/* Valid values for QueryItemType: */
#define QI_VAL 1
#define QI_OPR 2
#define QI_VALSTOP 3			/* This is only used in an intermediate stack
								 * representation in parse_tsquery. It's not a
								 * legal type elsewhere. */

/*
 * QueryItem is one node in tsquery - operator or operand.
 */
typedef struct
{
	QueryItemType type;			/* operand or kind of operator (ts_tokentype) */
	uint8		weight;			/* weights of operand to search. It's a
								 * bitmask of allowed weights. if it =0 then
								 * any weight are allowed. Weights and bit
								 * map: A: 1<<3 B: 1<<2 C: 1<<1 D: 1<<0 */
	bool		prefix;			/* true if it's a prefix search */
	int32		valcrc;			/* XXX: pg_crc32 would be a more appropriate
								 * data type, but we use comparisons to signed
								 * integers in the code. They would need to be
								 * changed as well. */

	/* pointer to text value of operand, must correlate with WordEntry */
	uint32
				length:12,
				distance:20;
} QueryOperand;


/*
 * Legal values for QueryOperator.operator.
 */
#define OP_NOT			1
#define OP_AND			2
#define OP_OR			3
#define OP_PHRASE		4		/* highest code, tsquery_cleanup.c */
#define OP_COUNT		4

extern PGDLLIMPORT const int tsearch_op_priority[OP_COUNT];

/* get operation priority by its code */
#define OP_PRIORITY(x)	( tsearch_op_priority[(x) - 1] )
/* get QueryOperator priority */
#define QO_PRIORITY(x)	OP_PRIORITY(((QueryOperator *) (x))->oper)

typedef struct
{
	QueryItemType type;
	int8		oper;			/* see above */
	int16		distance;		/* distance between agrs for OP_PHRASE */
	uint32		left;			/* pointer to left operand. Right operand is
								 * item + 1, left operand is placed
								 * item+item->left */
} QueryOperator;

/*
 * Note: TSQuery is 4-bytes aligned, so make sure there's no fields
 * inside QueryItem requiring 8-byte alignment, like int64.
 */
typedef union
{
	QueryItemType type;
	QueryOperator qoperator;
	QueryOperand qoperand;
} QueryItem;

/*
 * Storage:
 *	(len)(size)(array of QueryItem)(operands as '\0'-terminated c-strings)
 */

typedef struct
{
	int32		vl_len_;		/* varlena header (do not touch directly!) */
	int32		size;			/* number of QueryItems */
	char		data[FLEXIBLE_ARRAY_MEMBER];	/* data starts here */
} TSQueryData;

typedef TSQueryData *TSQuery;

#define HDRSIZETQ	( VARHDRSZ + sizeof(int32) )

/* Computes the size of header and all QueryItems. size is the number of
 * QueryItems, and lenofoperand is the total length of all operands
 */
#define COMPUTESIZE(size, lenofoperand) ( HDRSIZETQ + (size) * sizeof(QueryItem) + (lenofoperand) )
#define TSQUERY_TOO_BIG(size, lenofoperand) \
	((size_t) (lenofoperand) > MaxAllocSize - HDRSIZETQ || \
	 (size) > (MaxAllocSize - HDRSIZETQ - (lenofoperand)) / sizeof(QueryItem))

/* Returns a pointer to the first QueryItem in a TSQuery */
#define GETQUERY(x)  ((QueryItem*)( (char*)(x)+HDRSIZETQ ))

/* Returns a pointer to the beginning of operands in a TSQuery */
#define GETOPERAND(x)	( (char*)GETQUERY(x) + ((TSQuery)(x))->size * sizeof(QueryItem) )

/*
 * fmgr interface functions
 * Note, TSQuery type marked as plain storage, so it can't be toasted
 * but PG_DETOAST_DATUM_COPY is used for simplicity
 */

static inline TSQuery
DatumGetTSQuery(Datum X)
{
	return (TSQuery) DatumGetPointer(X);
}

static inline TSQuery
DatumGetTSQueryCopy(Datum X)
{
	return (TSQuery) PG_DETOAST_DATUM_COPY(X);
}

static inline Datum
TSQueryGetDatum(const TSQueryData *X)
{
	return PointerGetDatum(X);
}

#define PG_GETARG_TSQUERY(n)		DatumGetTSQuery(PG_GETARG_DATUM(n))
#define PG_GETARG_TSQUERY_COPY(n)	DatumGetTSQueryCopy(PG_GETARG_DATUM(n))
#define PG_RETURN_TSQUERY(x)		return TSQueryGetDatum(x)

#endif							/* _PG_TSTYPE_H_ */