Phone - Display and store UK telephone numbers ============================================== File: Phone - Update: 1.13 Author: J.G.Harston - Date: 15-Mar-2014 The Phone library provides functions to store, retrieve and display correctly formatted UK telephone numbers. It is an update from the previous library that was only able to cope with 01 and 02 geographic ranges. With the introduction by Ofcom of the 03 geographic range, this library has been updated to cope with the full UK telephone number range. Introduction ============ UK telephone numbers are a zero followed by ten digits. This library handles telephone numbers internally as 5-byte floats which can be stored in any normal real variable, for example mynum=FNPhone_FromStr(mynum$). 4-byte integers used by earlier version of the Phone library are also recognised. The values used to represent telephone numbers are opaque values which should not be interpreted outside the Phone functions. Requirements and dependancies ============================= BASIC V or equivalent with the '|' operator. Other versions of BASIC will only handle 01 and 02 number ranges. Convert telephone number string to value ======================================== DEFFNPhone_FromStr(phone$) Converts the supplied telephone number into a five-byte representation. Any non-digit characters are ignored. For example: num=FNPhone_FromStr("0114 200 0000") num=FNPhone_FromStr("01142000000") num=FNPhone_FromStr("(0114) 200-0000") Convert value to telephone number string ======================================== DEFFNPhone_ToStr(number) Converts the passed representation of a UK telephone number into a fixed- length 11-character telephone number string. The only valid values to pass are those previously returned from FNPhone_FromStr(). Four-byte values used by the earlier Phone library are also recognised. For example: num$=FNPhone_ToStr(num) num$=FNPhone_ToStr(FNPhone_FromStr("(0114) 200-0000") Convert value to formatted telephone number string ================================================== DEFFNPhone_ToStrF(number) Converts the passed representation of a UK telephone number into a correctly-formatted fixed-length 13-character telephone number string. The only valid values to pass are those previously returned from FNPhone_FromStr(). Four-byte values used by the earlier Phone library are also recognised For example: num$=FNPhone_ToStrF(num) num$=FNPhone_ToStrF(FNPhone_FromStr("01142000000") Examples ======== DIM num(9) FOR n%=0 TO 9 INPUT "Phone number: "A$ num(n%)=FNPhone_FromStr(A$) NEXT FOR n%=0 TO 9 PRINT ;n;": ";FNPhone_ToStrF(num(n%)) NEXT REM Display phone number formatting for number ranges FOR A=10 TO 99 PRINT FNPhone_ToStrF(FNPhone_FromStr("0"+STR$A+"00000000")) IF A<20:PRINT FNPhone_ToStrF(FNPhone_FromStr("0"+STR$A+"10000000")) NEXT Notes ===== Behaviour is undefined for numbers outside the UK number range of 01 to 09 and for numbers passed to Phone_FromStr() without an area code prefix. 00 is the UK dialing prefix for international dialing and such numbers are outside the scope of a UK telephone number handling scheme. The four-byte and five-byte values used to represent telephone numbers are opaque values that only have meaning when passed to and from Phone functions and cannot be manipulated outside Phone functions to give any meaningful results. Formatting of UK telephone numbers ================================== Since the reorganisation of the UK telephone numbering scheme in the 1990s UK telephone numbers have a consistant formatting scheme. All UK telephone numbers have a total of 11 digits starting with a 0, split into a 3-, 4- or 5-digit dialing code followed by a 8-, 7- or 6-digit local number. 6-digit geographic numbers: 01xxx yyyyyy 7-digit geographic numbers: 011x yyy-zzzz 01x1 yyy-zzzz 8-digit geographic numbers: 02x yyyy-zzzz All other numbers: 0xxx yyy-zzzz Technical information ===================== You must not rely on the internal representation the Phone library uses to store phone numbers. These details are presented for information only and may be subject to change. The full 11-digit phone number range is stored in a 5-byte real number as follows. The exponent holds a number BCD number &00-&99 representing the second and third digits of the phone number. The mantissa holds a BCD number &00000000-&99999999 representing the 4th to 11th digits. If the exponent is zero, then the mantissa is a 4-byte integer holding an 01-/02- range number. 0 a b c d e f g h i j +---+ +---++---++---++---+ 0 |a b| |c d||e f||g h||i j| +---+ +---++---++---++---+ exponent mantissa The data is stored in memory as follows: +---+ +---+ +---+ +---+ +---+ |i j| |g h| |e f| |c d| |a b| +---+ +---+ +---+ +---+ +---+ LSB mantissa MSB exponent The 2 billion geographic numbers 01- and 02- can fit into the range of a 32-bit integer. 01- phone numbers are stored as decimal numbers 1000000000 to 1999999999, 02- numbers are stored as 0000000000 to 0999999999. Version History =============== 1.00 23-Apr-1995 First version written. 1.10 20-Aug-2009 Updated to handle whole UK telephone number range. 1.11 20-Aug-2009 Optimised Acorn/Russell storage access. 1.12 25-Aug-2009 The | function stores data identically on all BBC BASICs. 1.13 15-Mar-2014 Tweeked so that code is interuptable on BB4W.