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 numers 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 '|' and 'END' functions. Pre-BASIC V 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 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.
The full 11-digit phone number range is stored in a 5-byte real number as
follows. The mantissa holds BCD digits, the exponent holds a decimal number
10 to 99. 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
For compatibility with data created with the earlier Phone library that only
supported the 01 and 02 ranges, the 4-byte values used by that library are also
recognised, and returned to represent the 01 and 02 ranges.
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.