convert.md

Converting between cty types

The convert package provides a standard set of type conversion routines for moving between types in the cty type system.

Conversion in this context means taking a given value and producing a new value of a different type that, in some sense, contains the same information. For example, the number 5 can be converted to a string as "5".

Specific conversion operations are represented by type Conversion, which is a function type that takes a single value as input and returns a value or an error.

"Safe" and "Unsafe" conversions

The convert package broadly organizes its supported conversions into two types.

"Safe" conversions are ones where all values of the source type can be represented in the target type, and thus the conversion is guaranteed to succeed for any value of the source type.

"Unsafe" conversions, on the other hand, are able to convert only a subset of values of the source type. Values outside of that subset will cause the conversion function to return an error.

Converting from number to string is safe because an unambiguous string representation can be created for any number. The converse is unsafe, because while a string like "2.5" can be converted to a number, a string like "bananas" cannot.

The calling application must choose whether to attempt unsafe conversions, depending on whether it is willing to tolerate conversions returning errors even though they ostensibly passed type checking. Operations that have both safe and unsafe modes come in couplets, with the unsafe version's name having the suffix Unsafe.

Getting a Conversion

To find out if a conversion is available between two types, an application can call either GetConversion or GetConversionUnsafe. These functions return a valid Conversion if one is available, or nil if not.

Note that there are no conversions from a type to itself. Callers should check if two types are equal before attempting to obtain a conversion between them.

As usual, cty.DynamicPseudoType serves as a special-case placeholder. It is used in two ways, depending on whether it appears in the source or the destination type:

• When a source type is dynamic, a special unsafe conversion is available that takes any value and passes it through verbatim if it matches the destination type, or returns an error if it does not. This can be used as part of handling dynamic values during a type-checking procedure, with the generated conversion serving as a run-time type check.

• When a destination type is dynamic, a simple passthrough conversion is generated that does not transform the source value at all. This is supported so that a destination type can behave similarly to a type description used for a conformance check, thus allowing this package to be used to attempt to make a type conformant, rather than merely check whether it already is.

Converting a Value

A value can be converted by passing it as the argument to any conversion whose source type matches the value's type. If the conversion is an unsafe one, the conversion function may return an error, in which case the returned value is invalid and must not be used.

As a convenience, the Convert function takes a value and a target type and returns a converted value if a conversion is available. This is equivalent to testing for an unsafe conversion for the value's type and then immediately calling any discovered conversion. An error is returned if a conversion is not available.

Type Unification

A related idea to type conversion is type unification. While conversion is concerned with going from a specific source type to a specific target type, unification is instead concerned with finding a single type that several other types can be converted to, without any specific preference as to what the final type is.

A good example of this would be to take a set of values provided to initialize a list and choose a single type that all of those values can be converted to, which then decides the element type of the final list.

The Unify and UnifyUnsafe functions are used for type unification. They both take as input a slice of types and then return, if possible, a single target type along with a slice of conversions corresponding to each of the input types.

Since many type pairs support type conversions in both directions, the unify functions must apply a preference for which direction to follow given such a pair of types. These functions prefer safe conversions over unsafe ones (assuming that UnifyUnsafe was called), and prefer lossless conversions over potentially-lossy ones.

Type unification is a potentially-expensive operation, depending on the complexity of the passed types and whether they are mutually conformant.

Conversion Charts

The foundation of the available conversions is the matrix of conversions between the primitive types. String is the most general type, since the other two primitive types have safe conversions to string. The full matrix for primitive types is as follows:

	string	number	boolean
string	n/a	unsafe	unsafe
number	safe	n/a	none
boolean	safe	none	n/a

The conversions for compound types are then derived from the above foundation. For example, a list of numbers can convert to a list of strings because a number can convert to a string.

The compound type kinds themselves have some available conversions, though:

	tuple	object	list	map	set
tuple	n/a	none	safe	none	safe+lossy
object	none	n/a	none	safe	none
list	unsafe	none	n/a	none	safe+lossy
map	none	unsafe	none	n/a	none
set	unsafe	none	safe	none	n/a

Conversions between compound kinds, as shown above, are possible only if their respective elements/attributes also have conversions available.

The conversions from structural types to collection types rely on type unification to identify a single element type for the final collection, and so conversion is possible only if unification is possible.

Conversion between Object Types

There are some special considerations for conversion between distinct object types that do not apply to conversion between types of other kinds.

For object types, convert implements structural typing behaviors, where the target type is considered to be a description of a set of attributes the final result should have. There are two important additional concerns that result from this design intent:

• If the input type has additional attributes that are not mentioned at all in the target type, those additional attributes are silently discarded during conversion, leading to a new object value that has a subset of the attributes of the input value, and whose type therefore conforms to the target type constraint.

• If any of the attributes of the target type are marked as optional using the currently-experimental cty.ObjectWithOptionalAttrs constructor, type conversion will tolerate those attributes being absent in the given type, and the resulting value will include appropriately-typed null value placeholders as the values of those omitted attributes.

  This behavior is subject to change even in future minor versions of the cty module, so that we can try it out with experimental versions of calling applications and adjust the details of the behavior if needed. Hopefully this mechanism will be stabilized in a future release, if those downstream experiments are successful.