[ 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).