2 Coercion

6.0.1.13

2 Coercion

package: sugar

Functions that coerce the datatype of a value to another type. Racket already has type-specific conversion functions. But if you’re handling values of indeterminate type — as sometimes happens in an untyped language — then handling the possible cases individually gets to be a drag.

2.1 Values

procedure
(->int v) → integer?
v : any/c

Convert v to an integer in the least surprising way, or raise an error if no conversion is possible.

Numbers are rounded down to the nearest integer.

Examples:

> (->int 3)
3
> (->int 3.5)
3
> (->int -2.5)
-3
> (->int (+ 3 (/ 1 2)))
3

Stringlike values — paths, symbols, and strings — are converted to numbers and rounded down.

Examples:

> (->int "3.5")
3
> (->int '3.5)
3
> (->int (string->path "3.5"))
3

Characters are directly converted to integers.

Examples:

> (->int #\A)
65
> (->int #\◊)
9674

Lists, vectors, and other multi-value datatypes return their length (using len).

Examples:

> (->int (list 5 6 7))
3
> (->int (hash 'a 1 'b 2 'c 3))
3

The function will raise an error if no sensible conversion is possible.

Example:

> (->int #t)
Can’t convert #t to integer

procedure
(->string v) → string?
v : any/c

Return the most natural string representation of v, or raise an error if none exists.

Examples:

> (->string "string")
"string"
> (->string 'symbol)
"symbol"
> (->string 98.6)
"98.6"
> (->string (string->path "stdio.h"))
"stdio.h"
> (->string #\A)
"A"
> (->string #t)
Can’t convert #t to string

procedure
(->symbol v) → symbol?
v : any/c

Same as ->string, but return a symbol rather than a string.

Examples:

> (->symbol "string")
'string
> (->symbol 'symbol)
'symbol
> (->symbol 98.6)
'|98.6|
> (->symbol (string->path "stdio.h"))
'stdio.h
> (->symbol #\A)
'A
> (->symbol #t)
Can’t convert #t to symbol

procedure
(->path v) → path?
v : any/c
procedure
(->complete-path v) → complete-path?
v : any/c

Same as ->string, but return a path (or complete path) rather than a string.

Examples:

> (->path "string")
#<path:string>
> (->path 'symbol)
#<path:symbol>
> (->complete-path 98.6)
#<path:/Users/MB/git/sugar/98.6>
> (->complete-path (string->path "stdio.h"))
#<path:/Users/MB/git/sugar/stdio.h>
> (->complete-path #\A)
#<path:/Users/MB/git/sugar/A>
> (->complete-path #t)
Can’t convert #t to complete-path

procedure
(->list v) → list?
v : any/c

If v is a listlike data type — a vector, set, stream, sequence, or list — convert it to a list. A hash or dictionary becomes a list using dict->list. If v is an atomic value, turn it into a single-member list.

Note that a string is treated as an atomic value rather than decomposed with string->list. This is done so the function handles strings the same way as symbols and paths.

Examples:

> (->list '(a b c))
'(a b c)
> (->list (list->vector '(a b c)))
'(a b c)
> (->list (make-hash '((k . v) (k2 . v2))))
'((k . v) (k2 . v2))
> (->list "string")
'("string")
> (->list 'symbol)
'(symbol)
> (->list (string->path "path"))
'(#<path:path>)
> (->list +)
'(#<procedure:+>)

procedure
(->vector v) → vector?
v : any/c

Same as ->list, but returns a vector rather than a list.

Examples:

> (->vector '(a b c))
'#(a b c)
> (->vector (list->vector '(a b c)))
'#(a b c)
> (->vector (make-hash '((k . v) (k2 . v2))))
'#((k . v) (k2 . v2))
> (->vector "string")
'#("string")
> (->vector 'symbol)
'#(symbol)
> (->vector (string->path "path"))
'#(#<path:path>)
> (->vector +)
'#(#<procedure:+>)

procedure
(->boolean v) → boolean?
v : any/c

Return #t for all v except #f, which remains #f.

Examples:

> (->boolean "string")
#t
> (->boolean 'symbol)
#t
> (->boolean +)
#t
> (->boolean '(l i s t))
#t
> (->boolean #f)
#f

procedure
(intish? v) → boolean?
  v : any/c
procedure
(stringish? v) → boolean?
  v : any/c
procedure
(symbolish? v) → boolean?
  v : any/c
procedure
(pathish? v) → boolean?
  v : any/c
procedure
(complete-pathish? v) → boolean?
  v : any/c
procedure
(listish? v) → boolean?
  v : any/c
procedure
(vectorish? v) → boolean?
  v : any/c

Predicates that report whether v can be coerced to the specified type.

Examples:

> (map intish? (list 3 3.5 #\A "A" + #t))
'(#t #t #t #f #f #f)
> (map stringish? (list 3 3.5 #\A "A" + #t))
'(#t #t #t #t #f #f)
> (map symbolish? (list 3 3.5 #\A "A" + #t))
'(#t #t #t #t #f #f)
> (map pathish? (list 3 3.5 #\A "A" + #t))
'(#t #t #t #t #f #f)
> (map complete-pathish? (list 3 3.5 #\A "A" + #t))
'(#t #t #t #t #f #f)
> (map listish? (list 3 3.5 #\A "A" + #t))
'(#t #t #t #t #t #t)
> (map vectorish? (list 3 3.5 #\A "A" + #t))
'(#t #t #t #t #t #t)

2.2 Coercion contracts

procedure
(coerce/int? v) → integer?
  v : any/c
procedure
(coerce/string? v) → string?
  v : any/c
procedure
(coerce/symbol? v) → symbol?
  v : any/c
procedure
(coerce/path? v) → path?
  v : any/c
procedure
(coerce/boolean? v) → boolean?
  v : any/c

If v can be coerced to the specified type, change it to that type, then return it. If not, raise the usual contract error. These contracts can be used with input or output values.

Examples:

> (define/contract (add-ints x y)
      (coerce/int? coerce/int? . -> . any/c)
      (+ x y))
; Input arguments will be coerced to integers, then added
> (add-ints 1.6 3.8)
4
> (define/contract (int-sum x y)
      (any/c any/c . -> . coerce/int?)
      (+ x y))
; Input arguments will be added, and the result coerced to an integer
> (int-sum 1.6 3.8)
5

Please note: this is not an officially sanctioned way to use Racket’s contract system, because contracts aren’t supposed to mutate their values (see make-contract).

But coercion contracts can be useful in two situations:

You want to be liberal about input types, but don’t want to deal with the housekeeping and manual conversions between types.
Your contract involves an expensive operation that you’d rather avoid performing twice.

← prev up next →

1	Installation & updates
2	Coercion
3	Container
4	Len
5	License & source code
	Index