class ref name: phone_number
category-group: people
layer: 7
header file: z_phone.h

description.
the phone number class (phone_number_o) basically represents a telephone number. At the present time (2016), it is extremely focused on American (ie USA) type phone numbers. With this object, you can parse a telephone number into its traditional components: country code (1 for USA), area code, exchange number (the first 3 digits of a 7-digit local number), and suffix. The latter term was concocted by Vettrasoft since there doesn't seem to be an official term for it (as far as we could find). Thus, given the phone number +1 (202) 456-1414 (the American "white house"), it would break down like so:

• +1: The country code. the "+" is simply the standard designator that starts a phone number which includes the country code. This number can be from 1 digit (1: USA & Canada; 7: Russia) to about 3 digits (966: Saudi Arabia; 234: Nigeria). There are also various combinations of major and minor parts for smaller countries or principalities belonging to other countries. Usually the country code syntax includes a dash ('-') separating the mother [/ruling] country from the lesser country. These for the most part are currently ignored.
• (202): the area code. "Area Code" is a uniquely American term; it may or may not have equivalents in other countries. American area codes often map loosely to a city, but often a big city will have several area codes. These numbers also morph over time, such as splitting into 2 numbers as the population grows larger, or even shifting over the geographical area it covers.
• 456 (of "456-1414"): the last 7 digits is consideered to be a "local" number. The first 3 digits often (but not 100% always) maps onto a local telephone "exchange" - a building serving the area that manages the 10,000 possible phone numbers.
• "-1414": this chunk of the phone number completes the full number, and [usually] maps onto a specific telephone. We call it a "suffix". Each such number may go to a real land line, or a cell phone; be unassigned; owned by a business or organization as part of a PBX set; etc.

The meanings, peculiarities, history and basically all the details about phone numbers can be the topic for a very large book and will be at best minimally covered here. When calling from one number to another, there can be a variety of ways to do it, using all sorts of rules on how to modify the full phone number to access it, usually depending on where you are, the type of phone number it is, and the type of phone you are calling from. For example, in America, when calling to a number in the same area code, only the first 7 digits are needed. In some countries, when calling to another city, a zero needs to be prepended to the area code (or equivalent term), or if the number is a cell phone, an '8' or '9' may need to be prepended, depending on the carrier.

It is hoped for one day that this object will encompass all these rules. For now, you can simply get and set values of a phone_number_o instance. The Z Directory phone number class started in 1998. This class is an orthodox object, which means you can store a phone number to a database (easily). In addition to the number syntax described above, in the Z Directory world, a phone number syntax has been custom extended a little. You can attach notes of a sort to a phone number. This is done by appending a string containing a phone number with codes such as "{d}" or "{note: alternate}". Also, the parsing supports unknown components of a phone number. This is done by filling in the unknown part with question marks ("?"). For example, a phone number with an unknown area code could be "(???) 867-5309" (Jenny's phone #), or one with an unknown exchange could be written "(212) ???-1212".

On the database side, a phone number is a "reparentable" record (/object). That is, it is intended to have an "owner". A phone number is typically owned by a person, a business, or an employee (a "worker") of a business. Thus, if "+7 (095) 985-3760" is the main phone number of a business (or organization; the Kremlin, in this case), the [orthodox] database record will have the "owner_tabid" column value set to the table ID of the "business" table, and the "owner" column value set to the "id" column value for the Kremlin's entry in the "business" table:

phone_number table:
+------+-------+-------------+-------------------+
|   id | owner | owner_tabid | free_text         |
+------+-------+-------------+-------------------+
|    7 |  1917 |  1666803056 | +7 (095) 985-3760 |
+------+-------+-------------+-------------------+
 
business table:
+------+--------------------------+------------+----------------+
| id   | full_name                | short_name | url0           |
+------+--------------------------+------------+----------------+
| 1916 | Roma Import & Export SAC | Roma Corp  |                |
| 1917 | Government of Russia     | Kremlin    | kremlin.gov.ru |
+------+--------------------------+------------+----------------+

The table ID values are internally handled by the database vendor. This may lead to problems if migrating data from one database vendor to another, as the values are hard-coded into the tables. The Z Directory provides a function to get such values via the subroutine zdb_tablename_to_ID().

member functions (primary)

phone_number_o()
SIGNATURE: phone_number_o()
SYNOPSIS: creates a a new phone # object, completely devoid of values.
 

phone_number_o(phone_number_o)
SIGNATURE: phone_number_o (const phone_number_o &rhs)
SYNOPSIS: creates a a new phone # object, based on the content found in object "rhs". rhs data will be copied.
 

operator = (phone_number_o)
SIGNATURE: const phone_number_o &operator = (const phone_number_o &rhs)
SYNOPSIS: The current object is set to that of "rhs".
 

destructor
SIGNATURE: ~phone_number_o ()
SYNOPSIS: destroys the class object instance.
TRAITS: virtual function
 

phone_number_o(<args>)
SIGNATURE: phone_number_o (const string_o &s)
 

phone_number_o(phone_number_o)
SIGNATURE: const phone_number_o &operator = (const string_o &s)
SYNOPSIS:
creates a a new phone # object, based on the content of string object 's'. the contents of 's' is parsed, and if it's a valid phone number, the object is set to that value.
 

operator !=()
SIGNATURE: int operator != (const phone_number_o &rhs) const
SYNOPSIS:
compares two phone number objects. if the phones are different, this function returns 1 (the converse of the "==" operator).
TRAITS: this function is inline
 

operator ==()
SIGNATURE: int operator == (const phone_number_o &rhs) const
SYNOPSIS:
compares two phone number objects. if the phones are the same, this function returns 1. It is the converse of of the "!=" operator.
 

country_code()
SIGNATURE: int country_code (int *pi = NULL) const
SYNOPSIS: returns two country code, if the object is set.
TRAITS: this function is inline
 

area_code()
SIGNATURE: const string_o &area_code (int *pi = NULL) const
SYNOPSIS: returns the area code component of a phone number
PARAMETERS

pi: an [optional] error indicator [output] variable. values:
0: no error, succesful lookup
zErr_NotInitialized: area code not set

RETURNS: [string] the area code, as text
 

exchange()
SIGNATURE: const string_o &exchange (int *pi = NULL) const;
TRAITS: this function is inline
 

suffix()
SIGNATURE: const string_o &suffix (int *pi = NULL) const
TRAITS: this function is inline
 

free_text()
SIGNATURE: const string_o &free_text (int *pi = NULL) const
TRAITS: this function is inline
 

is_set()
SIGNATURE: boolean is_set () const
TRAITS: this function is inline
 

is_parsed()
SIGNATURE: boolean is_parsed () const
TRAITS: this function is inline
 

is_type()
SIGNATURE: boolean is_type (const z_Phone_Type) const
 

strict_mod()
SIGNATURE: boolean strict_mode() const
TRAITS: this function is inline
 

is_american_style_phone()
SIGNATURE: boolean is_american_style_phone () const
 

is_american_syntax()
SIGNATURE: boolean is_american_syntax (const string_o &, int *pi = NULL)
TRAITS: this function is static. that is, it is a global-level function.
 

set_countrycode()
SIGNATURE: int set_countrycode (const string_o &)
 

set_areacode()
SIGNATURE: int set_areacode (const string_o &)
 

set_exchange()
SIGNATURE: int set_exchange (const string_o &)
 

set_suffix()
SIGNATURE: int set_suffix (const string_o &)
 

set_freetext()
SIGNATURE: int set_freetext (const string_o &)
 

set_rank()
SIGNATURE: int set_rank (const string_o &)
 

set()
SIGNATURE: int set (const string_o &, int *pi = NULL)
 

set_type()
SIGNATURE: int set_type (enum z_Phone_Type)
 

set_options()
SIGNATURE: int set_options (const textstring_o &, int *pi)
 

set_showopts()
SIGNATURE: int set_showopts (boolean = TRUE)
TRAITS: this function is inline
 

set_fax_isoption()
SIGNATURE: int set_fax_isoption (boolean = TRUE)
TRAITS: this function is inline
 

set_strict_mode()
SIGNATURE: int set_strict_mode (const boolean = TRUE)
TRAITS: this function is inline
 

reset()
SIGNATURE: int reset ()
 

phone_number_o()
SIGNATURE: phone_number_o *clone () const
TRAITS: this function is inline
 

operator =()
SIGNATURE: orthodox_o &operator = (const rec_dbag_o &)
 

bad_reference()
SIGNATURE: const phone_number_o &bad_reference ()
TRAITS: this function is static. that is, it is a global-level function.
 

phone_str_to_type()
SIGNATURE: z_Phone_Type phone_str_to_type (const string_o &, boolean = FALSE, int *pi = NULL)
TRAITS: this function is static. that is, it is a global-level function.
 

phone_type_to_str()
SIGNATURE: string_o phone_type_to_str (z_Phone_Type, boolean = FALSE, int *pi = NULL)
TRAITS: this function is static. that is, it is a global-level function.
 

set_default_ccode()
SIGNATURE: int set_default_ccode (const string_o &s)
TRAITS: this function is static. that is, it's a global-level function.
 

default_ccode()
SIGNATURE: const string_o &default_ccode()
TRAITS: this function is static. that is, it is a global-level function.
 

copy_to_databag()
SIGNATURE: int copy_to_databag (rec_dbag_o &)
 

phone_whereclause()
SIGNATURE: int phone_whereclause (string_o &sz_clouse, int *pi = NULL)
SYNOPSIS: This function returns a string, which could be used in in SQL queries to find the current object's phone number
 

get_value()
SIGNATURE: const string_o get_value (const string_o &, int *pi) const
 

print()
SIGNATURE: string_o print (int *pi = NULL) const
 

string_o conversion operator()
SIGNATURE: operator string_o () const
 

operator <<()
SIGNATURE: friend std::ostream &operator << (std::ostream &, const phone_number_o &)
TRAITS: this function is a friend of the phone_number_o class
 

z_cleanup_phonestr()
SIGNATURE: int z_cleanup_phonestr (const string_o &sfon, string_o &sot, const string_o &scc = "US", int *pi = NULL)
PARAMETERS

• sfon: a string containing a phone number.
• scc: the country code to be applied to this phone number
• pi: [output] error indicator variable. values:
  0: successful cleanup
  zErr_Param_NotSet: empty input
  zErr_NoMatch: invalid [2-digit] country code
  zErr_Data_Unexpected: in the text of the phone number, in 'sfon', we got "+[n]," but 'n' does not match the country code

TRAITS: this is a global-scope function, related to but not part of the phone_number_o class.
 

z_str_lookslike_phone()
SIGNATURE: boolean z_str_lookslike_phone (const string_o &sin, string_o &sot, const char * = "-", boolean = FALSE, int *pi = NULL)
TRAITS: this is a global-scope function, related to but not part of the phone_number_o class.
 

z_str_lookslike_American_phone()
SIGNATURE: boolean z_str_lookslike_American_phone (const string_o &sin, string_o &sot, boolean only = FALSE, int *pi = NULL)
SYNOPSIS:
searches for strings in 's' that resemble an American-style (could be Canadian) phone number, and if there's a match, converts it to standard format.
PARAMETERS

• sin: a string containing a phone number.
• sot: the phone number, in standard format. may be the same
• as the input, or different. if the phone number given in the
• input ('sin') is invalid, this parameter is not set.
• only: if TRUE, the contents of 'sin' must be a phone number only. if FALSE, Z Directory extended notes can be part of the phone string (in 'sin').
• pi: [output] error indicator variable. values:
  0: successful check
  zErr_Param_NotSet: theh input string is empty
  zErr_Param_BadFormat: no closing ')' found

TRAITS: this is a global-scope function, related to but not part of the phone_number_o class.
 

zis_valid_phonecode()
SIGNATURE: boolean zis_valid_phonecode (int x, string_o &s, int *pi = NULL)
SYNOPSIS: does a simple table lookkup to check and provide the country code corresponding to the country phone code
PARAMETERS

• x: a phone number's country code
• s: the 2-digit country code corresponding to x
• pi: [output] error indicator variable. values:
  0: successful lookup
  zErr_Index_OutofBounds: x is 0 or negative, or greater than the highest-valued country phone code (as of this writing, 998 (Uzbekestan))
  zErr_NoMatch: no country found for 'x'

DESCRIPTION:
if x=1, this will set 's' to "US" and function returns TRUE. if x=7, this will set 's' to "RU" and function returns TRUE. if x is -10, 'pi' will be set to zErr_Index_OutofBounds and this function will return FALSE.
 

z_country_to_phone_code()
SIGNATURE: int z_country_to_phone_code (const string_o &, int * = NULL)
SYNOPSIS: given a 2-digit country code, this returns the country phone code (as an integer number).
 

z_country_to_phone_code()
SIGNATURE: int z_country_to_phone_code (const string_o &, int * = NULL)
 

z_phone_stripnotes()
SIGNATURE: int z_phone_stripnotes (string_o &s, string_o &se, int *pi = NULL)
SYNOPSIS:
given a phone number with Z Directory notes-extensions (in input parameter 's'), this function strips the extensions away and returns it in 'se'.
DESCRIPTION: this is really a thin convenience function, built on top of z_phone_notestr().
 

z_phone_notestr()
SIGNATURE: count_t z_phone_notestr (string_o &es, string_o &se, int *pi = NULL)
SYNOPSIS:
given a phone number with Z Directory notes-extensions (in input parameter 's'), this function returns the extensions in output parameter 'se'
 

history.

Tue 01/06/1998: started on an area code class
??? 01/27/1998: added "is_valid_syntax()"
Thu 03/19/1998: adding "{}" parsing
Fri 03/20/1998: adding mystery values ("???")
Mon 04/06/1998: table schema: added extra byte to "value"
Sat 07/04/1998: folded it into the Z Directory
Mon 07/06/1998: table schema: changed "value" -> "exchange"+"suffix"
Mon 07/13/1998: table schema: "serial" -> "int unique" (new orthodoxy)
Mon 10/19/1998: phone_str_to_type() - added "is_long" input parameter
Fri 10/23/1998: set_type(): added data-bag mirroring
??? 11/20/2001: phone_number_o::set() mask changed [--Max]
Fri 06/21/2002: is_american_syntax() name change ("is_valid_syntax()")
Mon 06/24/2002: get_phone_where_clouse() member function name change
Mon 09/09/2002: deleting 'title' [--GeG]; clean-up RDBMS fields
Thu 03/19/1998: is_american_syntax(): added " {text}" syntax
Fri 05/31/2013: added z_fix_phone_number() [--GeG]
Tue 06/04/2013: created z_phone_stripnotes()
Mon 10/14/2013: z_str_lookslike_American_phone() default country changed
Fri 07/15/2016: created z_cleanup_phonestr()
Fri 07/16/2016: started to overhaul z_str_lookslike_phone()