From d6952121e0a4654c7d94bfe679c97afac8f66ce9 Mon Sep 17 00:00:00 2001 From: Martin Pool Date: Fri, 27 Nov 2015 17:35:12 -0800 Subject: [PATCH] Attempted documentation of coercions Trying to summarize here only the cases that will make sense at the level of the rust book --- src/doc/book/casting-between-types.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/src/doc/book/casting-between-types.md b/src/doc/book/casting-between-types.md index 4c520e3d6a80..a5849e2f0511 100644 --- a/src/doc/book/casting-between-types.md +++ b/src/doc/book/casting-between-types.md @@ -5,6 +5,22 @@ different types between each other. The first, `as`, is for safe casts. In contrast, `transmute` allows for arbitrary casting, and is one of the most dangerous features of Rust! +# Coercion + +Coercion between types is implicit and has no explicit syntax. Coercion occurs +in `let`, `const`, and `static` statements; in function call arguments; in +field values in struct initialization; and in a function result. + +The main cases of coercion are: + + * `&mut T` to `&T` + + * `*mut T` to `*const T` + + * `&T` to `*const T` + + * `&mut T` to `*mut T` + # `as` The `as` keyword does safe casting: @@ -31,10 +47,10 @@ For example: ```rust let a = "hello"; -let b = a as String +let b = a as String; ``` -Coercions always occur implicitly so this form is only for clarity. +All coercions will be made implicitly when necessary and unambiguous. ## Numeric casts @@ -58,7 +74,7 @@ Perhaps surprisingly, it is safe to cast pointers to and from integers, and to cast between pointers to different types subject to some constraints. It is only unsafe to dereference the pointer. -* `e` has type `*T`, `U` is a pointer to `*U_0`, and either `U_0: Sized` or +* `e` has type `*T`, `U` has type `*U_0`, and either `U_0: Sized` or unsize_kind(`T`) = unsize_kind(`U_0`); a *ptr-ptr-cast* * `e` has type `*T` and `U` is a numeric type, while `T: Sized`; *ptr-addr-cast* * `e` is an integer and `U` is `*U_0`, while `U_0: Sized`; *addr-ptr-cast*