[ Strings and Atoms | Reference Manual | Alphabetic Index ]

# number_string(?Number, ?String)

Conversion between any number and a string.

Number
  Number or variable.
String
  String or variable.

## Description

If String is instantiated, its contents is interpreted as a number which is in turn unified with Number.

If Number is instantiated and String is a variable, String is bound to the textual representation of the number as writeq/1 would produce it.

If String does not represent a number, then number_string/2 fails. The string must not contain leading or trailing white space. For the exact number token syntax, see the User Manual Syntax Appendix, and note that details may depend on the context module's syntax options.

### Modes and Determinism

- number_string(+, -) is det
- number_string(-, +) is semidet

### Modules

This predicate is sensitive to its module context (tool predicate, see @/2).

### Fail Conditions

Fails if String does not represent a number

### Exceptions

(5) type error
  Number is instantiated, but not to an number.
(5) type error
  String is instantiated, but not to a string.
(4) instantiation fault
  Both arguments are free variables (non-coroutine mode only).

## Examples

       Success:
       number_string(1989,X).       (gives X = "1989").
       number_string(-7,X).         (gives X = "-7").
       number_string(124.5,X).      (gives X = "124.5").
       number_string(X,"+12").      (gives X = 12).
       number_string(X,"-7").       (gives X = -7).
       number_string(N,"123.4").     (gives N = 123.4).
       number_string(3.0,"3.0").
       number_string(3.0,"+3.00").
       Fail:
       number_string(N,"- 15").
       number_string(N," +15").
       number_string(N,"2 ").
       number_string(N,".5").
       number_string(N,"Abcd").
       number_string(222,"123").
       Error:
       number_string(N,S).          (Error 4).
       number_string(a,"12").       (Error 5).
       number_string(N,1234).       (Error 5).

## See Also

atomics_to_string / 2, term_string / 2, atom_string / 2, number / 1, sprintf / 3, split_string / 4