cast

Documentation

Overview

Package cast defines the semantically allowed casts and their information.

Note that it does not provide the mechanism to perform the evaluation of these casts.

Index

• func CastTypeName(t *types.T) string
• func ForEachCast(...)
• func LookupCastVolatility(from, to *types.T) (_ volatility.V, ok bool)
• func OIDInCastMap(src, tgt oid.Oid) bool
• func ValidCast(src, tgt *types.T, ctx Context) bool
• type Cast
  • func LookupCast(src, tgt *types.T) (Cast, bool)
• type Context
  • func (cc Context) PGString() string
  • func (cc Context) String() string
• type ContextOrigin

Functions

func CastTypeName

func CastTypeName(t *types.T) string

CastTypeName returns the name of the type used for casting.

func ForEachCast

func ForEachCast(
	fn func(
		src oid.Oid, tgt oid.Oid, castCtx Context, ctxOrigin ContextOrigin, v volatility.V,
	),
)

ForEachCast calls fn for every valid cast from a source type to a target type.

func LookupCastVolatility

func LookupCastVolatility(from, to *types.T) (_ volatility.V, ok bool)

LookupCastVolatility returns the Volatility of a valid cast.

func OIDInCastMap

func OIDInCastMap(src, tgt oid.Oid) bool

OIDInCastMap checks to see if the cast is in the cast map. This bypasses a few false equivalences found in LookupCast. You are more likely using to use LookupCast.

func ValidCast

func ValidCast(src, tgt *types.T, ctx Context) bool

ValidCast returns true if a valid cast exists from src to tgt in the given context.

Types

type Cast

type Cast struct {
	// MaxContext is the maximum context in which the cast is allowed. A cast
	// can only be performed in a context that is at or below the specified
	// maximum context.
	//
	// ContextExplicit casts can only be performed in an explicit context.
	//
	// ContextAssignment casts can be performed in an explicit context or in
	// an assignment context in an INSERT, UPSERT, or UPDATE statement.
	//
	// ContextImplicit casts can be performed in any context.
	MaxContext Context

	// Volatility indicates whether the result of the cast is dependent only on
	// the source value, or dependent on outside factors (such as parameter
	// variables or table contents).
	Volatility volatility.V
	// VolatilityHint is an optional string for volatility.Stable casts. When
	// set, it is used as an error hint suggesting a possible workaround when
	// stable casts are not allowed.
	VolatilityHint string
	// contains filtered or unexported fields
}

Cast includes details about a cast from one OID to another.

TODO(mgartner, otan): Move PerformCast logic to this struct.

func LookupCast

func LookupCast(src, tgt *types.T) (Cast, bool)

LookupCast returns a cast that describes the cast from src to tgt if it exists. If it does not exist, ok=false is returned.

type Context

type Context uint8

Context represents the contexts in which a cast can be performed. There are three types of cast contexts: explicit, assignment, and implicit. Not all casts can be performed in all contexts. See the description of each context below for more details.

The concept of cast contexts is taken directly from Postgres's cast behavior. More information can be found in the Postgres documentation on type conversion: https://www.postgresql.org/docs/current/typeconv.html

const (

	// ContextExplicit is a cast performed explicitly with the syntax
	// CAST(x AS T) or x::T.
	ContextExplicit Context
	// ContextAssignment is a cast implicitly performed during an INSERT,
	// UPSERT, or UPDATE statement.
	ContextAssignment
	// ContextImplicit is a cast performed implicitly. For example, the DATE
	// below is implicitly cast to a TIMESTAMPTZ so that the values can be
	// compared.
	//
	//   SELECT '2021-01-10'::DATE < now()
	//
	ContextImplicit
)

func (Context) PGString

func (cc Context) PGString() string

PGString returns the representation of Context as an abbreviated string.

func (Context) String

func (cc Context) String() string

String returns the representation of Context as a string.

type ContextOrigin

type ContextOrigin uint8

ContextOrigin indicates the source of information for a cast's maximum context (see cast.MaxContext below). It is only used to annotate entries in castMap and to perform assertions on cast entries in the init function. It has no effect on the behavior of a cast.

const (

	// ContextOriginPgCast specifies that a cast's maximum context is based on
	// information in Postgres's pg_cast table.
	ContextOriginPgCast ContextOrigin
	// ContextOriginAutomaticIOConversion specifies that a cast's maximum
	// context is not included in Postgres's pg_cast table. In Postgres's
	// internals, these casts are evaluated by each data type's input and output
	// functions.
	//
	// Automatic casts can only convert to or from string types [1]. Conversions
	// to string types are assignment casts and conversions from string types
	// are explicit casts [2]. These rules are asserted in the init function.
	//
	// [1] https://www.postgresql.org/docs/13/catalog-pg-cast.html#CATALOG-PG-CAST
	// [2] https://www.postgresql.org/docs/13/sql-createcast.html#SQL-CREATECAST-NOTES
	ContextOriginAutomaticIOConversion
	// ContextOriginLegacyConversion is used for casts that are not supported by
	// Postgres, but are supported by CockroachDB and continue to be supported
	// for backwards compatibility.
	ContextOriginLegacyConversion
)