Andromeda Class Library

Table Of Contents

1 class String

1.1 Construction and assignment.

1.2 Relational operators.

1.3 Adding strings together.

1.4 String length, testing and character access

1.5 Substring expressions.

1.6 Numerical Conversion

1.7 Shifting

1.8 Operations

1.9 Searching in Strings

1.10 Splitting Strings into SuperStrings

1.11 Stream I/O

1.12 Regular Expressions

1.13 See Also

2 class SuperString

2.1 Construction and assignment.

2.2 SuperString length, testing and element access

2.3 Adding to SuperStrings

3 date - Date class

3.1 Construction

3.2 Assignment

3.3 Conversion

3.4 Relational operations

3.5 Attributes

3.6 Operations

3.7 Arithmetic

3.8 Stream I/O

3.9 SEE ALSO

4 hour - Time class

4.1 Construction and assigment

4.2 Conversion

4.3 Relational operations

4.4 Attributes

4.5 Arithmetic

4.6 Stream I/O

4.7 SEE ALSO

5 UTC - Universal Time Coordinated class

5.1 Construction and assignment

5.2 Conversion

5.3 Relational operations

5.4 Attributes

5.5 Arithmetic

5.6 Stream I/O

6 Integer - Arbitrary length integer numbers

6.1 Construction

6.2 Conversion

6.3 Operators

6.4 Functions

6.5 SEE ALSO

7 xml - XML document classes

7.1 Class xml

7.2 class xml_node

7.3 class xml_element : xml_node

8 configuration - Class for configuration parameters

8.1 Class configuration

1 class String

#include <String.h>

The C++ String class can be used to represent character strings and perform operation upon them. Many operations are defined for normal operators but may have different semantics. E.g. the + operator is used to concatenate (add) strings together.

Substrings may be selected from strings to create other strings. Also, substrings have lvalue semantics, meaning a string may be assigned to a substring expression.

1.1 Construction and assignment.

String()
The default constructor creates an empty string.
String(char)
String(const char *)
String(const String &)

Other constructors are provided to initialize strings from character pointers, single characters or other strings. These constuctors also take care of typecasting: 

String x;          // Contruct an empty string
String abc("abc"); // Convert a char * to a string
String p('p');     // A string with one character in it.

Another string (or string expression), a char* or a single character can be assigned to a string: 

String x, y;

x = "abc";
y = x;
x = 'p';

1.2 Relational operators.

All relational operators (==, != , <, <=, > and >=) are available to compare strings alphabethically. Note that the comparison is done in the local character set, which will be ASCII in most cases. This also means that case is significant.

1.3 Adding strings together.

String can be added together, i.e. concatenated, with the + operator. Of course, the += operator can be used as well. Example: 

String x, y, z;

x = "abc"
y = "def"
z = x + y;   //  z = "abcdef"
y += x;      //  y = "defabc"

1.4 String length, testing and character access

The length of a string can be determined with the ~ operator. Do not confuse this with the bit-wise inversion operator ! 

String x = "Hello";
int    l = ~x;      // l = 5

The test for an empty string is done with the ! operator. Note that there is no test for a non-empty string. 

if (!x)
   cout << "String x is empty\n";

Access to individual characters is provided like in ordinary C strings. The [] operator selects an individual character for both read and write access: 

String x = "Hello";

char c = x[1];       // c = 'e'
x[2] = 'L';          // x = "HeLlo"

1.5 Substring expressions.

A substring is a part of a string denoted by its start index and its length. The start index is counted from zero. To extract a substring from a string use: 

String x = "abcdefghijkl";
String y = x(3,5);         // y = "defgh"

A substring expression can also be used as an lvalue. This means that a string can be assigned to a substring. The length of the substring does not need to be equal to the length of the string that is assigned to it. 

String x = "abcdefghijkl";
String y = "12345678";

x(3,5) = y;           // x = "abc12345678ijkl"

Note that assigning a string to a zero-length substring will simply insert the a string into another string. Reversely, assigning an empty string to a substring will remove the characters from the original string. 

String x = "abcdefghijkl";
String y = "12345678";

x(3,0) = y;           // x = "abc12345678defghijkl"
x(11,5) = "";         // x = "abc12345678ijkl"

This property can be used to truncate a string to its first n characters by: 

x(n, ~x-n) = "";

1.6 Numerical Conversion

Strings are coverted to and from numerical types (integer or floating point) by constructors and conversion operators. A numerical value is converted to a string with the number constructor: 

String n(12);   // n = "12"
String x(2.32); // x = "2.32"

These functions use a default format to convert the number to a string. Specifically, an integer is converted with the "%d" format from printf and a floating point is converted with the "%g" format.

A string is converted to a number with the type-casting operators: operator long() and operator double(). The conversion to a long integer recognizes C syntax for numerical literals. Numbers starting with '0' are regarded as octal and numbers starting with '0x' are regarded as hexadecimal.

Special member functions allow conversion of strings to and from numbers in a specific format. The functions dec(), oct() and hex() convert the string using decimal, octal and hexadecimal, respectively.

1.7 Shifting

Shifting a string moves all characters in the string a number of places to the left or to the right. Characters on the other end of the string simply fall off. Unlike shifting a binary number, shifting a string does not pad the string. Rather, shifting a string n places either to the left or to the right, renders the string n characters shorter. Example: 

"abcdefgh" << 3 = "defgh"
"abcdefgh" >> 3 = "abcde"

The shift operators << and >> can be combined with assignment: <<= and >>=. Do not confuse these shift operators with stream I/O operators.

1.8 Operations

String upper(void)
Convert the string to all upper-case characters.
String lower(void)
Convert the string to all lower-case characters.

1.9 Searching in Strings

int in(String &x)
Find the string x within the string. Returns the index where x was found. Returns -1 if x was not found in the string. see also strstr().

1.10 Splitting Strings into SuperStrings

SuperString split(String &separator)
Return a list of the words in the string, using separator as the delimiter string. 
String numbers("2,4,7");
numbers.split(",");  // "2" "4" "7"
Splitting an empty string will result in a SuperString with an empty string as its only element. The separator can be a multiple character string, for example: 
String somexml("A&amp;B&amp;C");
somexml.split("&amp;");   // "A" "B" "C"
Consecutive separators are not grouped together and are deemed to delimit empty strings, for example: 
String numbers("3.14   42");   //  Note 3 spaces
numbers.split(" ");   // "3.14" "" ""  "42"
This also happens with separators at the start and the end of the string.
SuperString tokenize(String &delimiters)
The tokenize() method breaks a string into a sequence of zero or more nonempty tokens. The delimiters argument specifies a set of bytes that delimit the tokens in the parsed string. A sequence of two or more contiguous delimiter bytes in the tokenized string is considered to be a single delimiter, and delimiter bytes at the start or end of the string are ignored. 
String example("aaa...bbb");
example.tokenize(".");   // "aaa" "bbb"

1.11 Stream I/O

A string can be written to a stream like any other type with the << operator. The left hand side of the expression must be a stream. To read a string from a stream, use the >> operator, with a stream on the left hand side: 

String x;

cin >> x;
cout << x;

Note that reading a string from a istream behaves like reading a character array from an istream. I.e., characters are read from the stream until the first whitespace character.

1.12 Regular Expressions

Regular expressions are handled by objects of class regex. Constructors allow the creation of regex objects from String objects, literal strings or other regex objects. 

String pattern("[a-z]+");
regex  word(pattern);
regex  number("[0-9]+");
regex  nr(number);

Regular expressions are primarily used to find patterns in text strings. The == operator performs the pattern matching. A relational expression returns true if the String matches the pattern, i.e. the pattern matches some part of the text in the String object. 

regex  nr("[0-9]+");
String x("abcdef"");
String y("abc123def");

x == nr;  // false
nr == y;  // true

A regular expression can be used in a substring expression. The substring selected from the target string is the first part that matches the regular expression. 

regex  nr("[0-9]+");
String y("abc123def456ghi");

x = y(nr);  // x = 123

1.13 See Also

2 class SuperString

A SuperString is a sequence of Strings, just like a String is a sequence of characters. A SuperString is in fact a string of Strings. Many operations that can be applied to String objects are also available for SuperSting objects, for example realtional operators, adding to SuperString objects, access to individual characters and 'substring' expressions. Split and join operations convert Strings into SuperStrings and vice versa. In that sense, split and join are complementary operations. The split() method of a string creates a SuperString. Conversily, the join() method of a SuperString creates a String.

2.1 Construction and assignment.

The default constructor creates an empty superstring, one that does not contain any strings. A superstring constructed from a string creates a superstring with one element. Other contructors can create a SuperString from STL collectors (list and vector) of strings.

SuperString()
The default constructor creates an empty string.
SuperString(const String &s)
Create a SuperSting with one element.
SuperString(const int n)
Create a SuperSting with n empty elements.

Another SuperString, String or SuperString expression can be assigned to a SuperString: 

SuperString x, y;
String z("abc");

x = z;  // Create a SuperString with one element
y = x;

2.2 SuperString length, testing and element access

The length of a SuperString can be determined with the ~ operator. This is the number of Strings in the SuperString. Do not confuse this with the bit-wise inversion operator ! 


SuperString xx(5);
int    l = ~xx;      // l = 5

The test for an empty string is done with the booloperator. This operator returns true if the SuperString object contains 1 or more Strings. It does not mean, however, that the String objects inside the SuperSting are not empty. 

if (!x)
   cout << "String x is empty\n";

Access to individual String elements is provided like in ordinary arrays. The [] operator selects an individual String for both read and write access: 

SuperString xx(3);

String s = "Hello";
xx[2] = s;

Access out of range will throw a std::out_of_range exception.

2.3 Adding to SuperStrings

SuperString objects can be added together, i.e. concatenated, with the + operator. Of course, the += operator can be used as well. Example: 

SuperString x, y, z;

SuperString x("abc");
SuperString y("def");

z = x + y;   //  z = [ "abc", "def" ]
y += z;      //  y = [ "def", "abc", "def" ]

split on a regex ? how to split on an empty string ? split and join for csv formats. quoting and escape , ? the + operater can add strings and superstrings to append or prepend the one to the other. the result us always a superstring. add characters and strings ? -> TODO stream io is not possible. the split and join functions must be used instead the substring expression creates a selection of strings of the superstring just like the substring expression of a string creates a selection of characters. a substring expression with regex argument selects all strings that match the expression. implements a sort of grep function. this means the substring may not be a consequitive subset of the superstring. assigning to a substring repleces all strings in the substring convert to and from a std vector or list

3 date - Date class

#include <date.h> date d;

The date class encapsulates the concept of a date, represented by days, months and years. It holds a day and a month, both between 0 and 255, and a year ranging from -32768 to +32767. Although full-range dates can be usefull in calulations, a real date should have a day between 1 and 31 inclusive, and a month between 1 and 12. Only such dates can be used as proper calender dates. A different kind of date may be used as a relative date to perform calculations. For example, to add 2 years, 3 months and 6 days to a date, a date like (6, 3, 2) can be created. All calculations with dates are based on the Julian calendar.

Parsing text into a date object is a challenging task. Partly because there are many ways to write dates but also because some ways to write a date are ambiguous. For example, the date 8-2-12 could mean August 2nd 2012, 12th of February 2008 or 8th of February 2012. These are some ways to write February 8th 2012 that are supported by the parser:

3.1 Construction

date()
The default constructor sets all elements (day, month and year) to 0.
date(unsigned day, unsigned month=0, short year=0)
Constructs a date object with the specified year, month and day. For this date object to be a proper calendar date, the month must be between 1 and 12 an the day myst be between 1 and the number of days in that month.
date(unsigned day, string month, short year)
date(String s)

3.2 Assignment

operator=(date &d)
operator=(String &s)
Parse string s and extract a day, month and year if the string contains an actual date.

3.3 Conversion

long()
Converts to the Julian date number. This is the number of days since the base date of the Julian calendar.
string()
Converts a date to an ASCII format.

3.4 Relational operations

The relational operators are defined with obvious meanings:

operator==(date d)
operator!=(date d)
operator<(date d)
operator<=(date d)
operator>(date d)
operator>=(date d)

3.5 Attributes

unsigned Day()
unsigned Month()
short Year()

3.6 Operations

int Leap()
Returns TRUE if this year is a leapyear. If this year is not a leapyear, leap() returns 0.
unsigned DaysInMonth()
Returns the number of days in this month, or zero if the month is not between 1 and 12.
unsigned YearDay()
Calculate the day of the year, starting from January 1st. For example, 1 means January 1st and the 22nd of February is 53. If the date is not a proper calendar date, return 0.
unsigned WeekDay()
Calculate the day of the week, where 1 is Monday and 7 is Sunday. If the date is not a proper calendar date, return 0.
string DayName()
string MonthName()
string WeekNumber()
Calculate the number of the week within the year.

3.7 Arithmetic

date operator+(date &d1, date &d2)
Add a number of days, months and years to a date. This is most usefull if one of the dates is a proper calendar date and the other is not.
date operator+=(date &d)
date operator+(long l, date &d)
Add a number of days to a date.
date operator+(date &d, long l)
date operator+=(long l)
Add l days to the date.
long operator-(date &d1, date &d2)
Calculate the number of days from d1 to d2.
date operator-(date &d1, date &d2)
date operator-=(date &d)
Subtract a number of days, months and years from the left-hand date.
date operator-=(long l)
Subtract l days.
date operator++()
date operator--()

3.8 Stream I/O

3.9 SEE ALSO

hour UTC

4 hour - Time class

#include <date.h> hour t;

The hour class encapsulates a time in hours, minutes and seconds. Most operators are defined to provide calculations just like integer numbers.

4.1 Construction and assigment

Objects of class hour can be constructed and assigned from integer numbers, String objects or other hour objects.

hour()
The default value is 0 hours, 0 minutes and 0 seconds.
hour(long)
A number of seconds.
hour(int hour, short minute, short second)
hour(const String)
A time can be written in various formats, such as "1134", meaning 11 hours and 34 minutes. The same time can be written as "11:34" or "11.34". A number of seconds can be added in the same manner. For example "11:34:25", "113425" or 11.34.25".
operator=(hour &)
operator=(String &)
operator=(long)
Assing a number of seconds.

4.2 Conversion

long()
Converts to a number of seconds.
String()
Converts to a textual representation of the hour in the format "hh:mm:ss".

4.3 Relational operations

operator==(hour &)
operator!=(hour &)
operator<(hour &)
operator<=(hour &)
operator>(hour &)
operator>=(hour &)

4.4 Attributes

int Hour()
short Minute()
short Second()

4.5 Arithmetic

hour operator+(hour t1, hour t2)
Add two hour objects, for example: 
    11:45:30 + 1:20:40 = 13:06:10
hour operator-(hour t1, hour t2)
Subtract two hour objects, for example: 
    11:05:30 - 1:20:40 =  9:44:50
hour &operator+=(hour t)
hour &operator-=(hour t)
hour &operator++()
Add one second.
hour &operator--()
Subtract one second.

4.6 Stream I/O

ostream &operator<<(ostream &str, hour &t)
istream &operator>>(istream &str, hour &t)

4.7 SEE ALSO

dateUTC

5 UTC - Universal Time Coordinated class

#include <date.h> UTC clock;

5.1 Construction and assignment

A UTC object can be constructed from its parts or by parsing from a String.

UTC()
The default constructor creates a default of its parts.
UTC(date d, hour t)
UTC(String s)
Parse the date and time from String s.
UTC(time_t clock)
Convert the UNIX time_t, defined as the number of seconds since the Epoch to a UTC object.

operator=(String &s)
Parse the date and time from String s.

5.2 Conversion

String()

time_t() - Convert to the UNIX time_t.

5.3 Relational operations

operator==(UTC &)
operator!=(UTC &)
operator<(UTC &)
operator<=(UTC &)
operator>(UTC &)
operator>=(UTC &)

5.4 Attributes

date day()hour hour()

5.5 Arithmetic

UTC operator+(UTC &t1, UTC &t2)
long operator-(UTC &t1, UTC &t2)
Calculate the number of seconds from t2 to t1;
UTC &operator+=(UTC &t)
UTC &operator-=(UTC &t)
UTC &operator++()
Add one second.
UTC &operator--()
Subtract one second.

5.6 Stream I/O

ostream &operator<<(ostream &str, UTC &t)
Write the date and time to the output stream in the default format.
istream &operator>>(istream &str, UTC &t)
Scan the input stream for a date and time.

6 Integer - Arbitrary length integer numbers

The Integer class provides multiple precision integer arithmetic facilities. Some representation details are discussed in the Representation section.

Integers may be up to b * ((1 << b) - 1) bits long, where b is the number of bits per short (typically 1048560 bits when b = 16). The implementation assumes that a long is at least twice as long as a short. This assumption hides beneath almost all primitive operations, and would be very difficult to change. It also relies on correct behavior of unsigned arithmetic operations.

Some of the arithmetic algorithms are very loosely based on those provided in the MIT Scheme `bignum.c' release, which is Copyright (c) 1987 Massachusetts Institute of Technology. Their use here falls within the provisions described in the Scheme release.

6.1 Construction

Integers may be constructed in the following ways:

Integer x;
Declares an uninitialized Integer.
Integer x = 2; Integer y(2);
Set x and y to the Integer value 2;
Integer u(x); Integer v = x;
Set u and v to the same value as x.

6.2 Conversion

long as_long()
Used to coerce an Integer back into longs via the long coercion operator. If the Integer cannot fit into a long, this returns MINLONG or MAXLONG (depending on the sign) where MINLONG is the most negative, and MAXLONG is the most positive representable long.
int fits_in_long()
Returns true iff the Integer is < MAXLONG and > MINLONG.
double as_double()
Coerce the Integer to a double, with potential loss of precision. +/-HUGE is returned if the Integer cannot fit into a double.
int fits_in_double()
Returns true iff the Integer can fit into a double.

6.3 Operators

All of the usual arithmetic operators are provided (+, -, *, /, %, +=, ++, -=, --, *=, /=, %=, ==, !=, <, <=, >, >=). All operators support special versions for mixed arguments of Integers and regular C++ longs in order to avoid useless coercions, as well as to allow automatic promotion of shorts and ints to longs, so that they may be applied without additional Integer coercion operators. The only operators that behave differently than the corresponding int or long operators are ++ and --. Because C++ does not distinguish prefix from postfix application, these are declared as void operators, so that no confusion can result from applying them as postfix. Thus, for Integers x and y, ++x; y = x; is correct, but y = ++x; and y = x++; are not.

Bitwise operators (~, &, |, ^, <<, >>, &=, |=, ^=, <<=, >>=) are also provided. However, these operate on sign-magnitude, rather than two's complement representations. The sign of the result is arbitrarily taken as the sign of the first argument. For example, Integer(-3) & Integer(5) returns Integer(-1), not -3, as it would using two's complement. Also, ~, the complement operator, complements only those bits needed for the representation. Bit operators are also provided in the BitSet and BitString classes. One of these classes should be used instead of Integers when the results of bit manipulations are not interpreted numerically.

6.4 Functions

The following utility functions are also provided. (All arguments are Integers unless otherwise noted).

void divide(const Integer& x, const Integer& y, Integer& q, Integer& r)
Sets q to the quotient and r to the remainder of x and y. (q and r are returned by reference).
Integer pow(const Integer& x, const Integer& p)
Returns x raised to the power p.
Integer Ipow(long x, long p)
Returns x raised to the power p.
Integer gcd(const Integer& x, const Integer& p)
Returns the greatest common divisor of x and y.
Integer lcm(const Integer& x, const Integer& p)
Returns the least common multiple of x and y.
Integer abs(const Integer& x)
Returns the absolute value of x.
Method: void Integer::negate()
Negates this in place.
Integer sqr(x)
returns x * x;
Integer sqrt(x)
returns the floor of the square root of x.
long lg(x)
returns the floor of the base 2 logarithm of abs(x)
int sign(x)
returns -1 if x is negative, 0 if zero, else +1. Using if (sign(x) == 0) is a generally faster method of testing for zero than using relational operators.
int even(x)
returns true if x is an even number
int odd(x)
returns true if x is an odd number.
void setbit(Integer& x, long b)
sets the b'th bit (counting right-to-left from zero) of x to 1.
void clearbit(Integer& x, long b)
sets the b'th bit of x to 0.
int testbit(Integer x, long b)
returns true if the b'th bit of x is 1.
Integer atoI(char* asciinumber, int base = 10)
converts the base base char* string into its Integer form.
void Integer::printon(ostream& s, int base = 10, int width = 0)
prints the ascii string value of (*this) as a base base number, in field width at least width.
ostream << x
prints x in base ten format.
istream >> x
reads x as a base ten number.
int compare(Integer x, Integer y)
returns a negative number if x<y, zero if x==y, or positive if x>y.
int ucompare(Integer x, Integer y)
like compare, but performs unsigned comparison.
add(x, y, z)
A faster way to say z = x + y.
sub(x, y, z)
A faster way to say z = x - y.
mul(x, y, z)
A faster way to say z = x * y.
div(x, y, z)
A faster way to say z = x / y.
mod(x, y, z)
A faster way to say z = x % y.
I_and(x, y, z)
A faster way to say z = x & y.
I_or(x, y, z)
A faster way to say z = x | y.
I_xor(x, y, z)
A faster way to say z = x ^ y.
lshift(x, y, z)
A faster way to say z = x << y.
rshift(x, y, z)
A faster way to say z = x >> y.
pow(x, y, z)
A faster way to say z = pow(x, y).
complement(x, z)
A faster way to say z = ~x.
negate(x, z)
A faster way to say z = -x.

6.5 SEE ALSO

The Integer class in the Gnu libg++ manual.

7 xml - XML document classes

#include <xml.h> xml document; xml_node node; xml_element element;

The collection of xml classes provide an easy way to process XML documents and to traverse the tree of XML data. Built upon the xml2 library on xmlsoft.org, the classes encapsulate concepts of XML data. After parsing an XML document with an xml object, the xml_node class can access the data of the XML document tree. A node in the tree can have any number of children which are also nodes. The child nodes are accessed by using the subscript operator with a numerical index. Elements of the XML data can be selected by name when a String argument is used with the subscript operator. Using this operator will return a vector of xml_element objects that hold all child elements having this name. xml data(filename); xml_node root(data); xml_node third = root[2]; String tagname("chapter"); std::vector <xml_element> all_chapters; all_chapters = root[tagname];

7.1 Class xml

An object of class xml holds an entire XML document. It supports reading and writing XML documents from and to files as well conversion of XML objects to and from String objects.

xml()
The default constructor creates an empty xml document.
xml(String s)
Parse the xml document from s.

operator=(String &s)
Parse the xml document from String s.

7.2 class xml_node

A node is the basic building block that makes up the tree of an XML document. There are several kinds of nodes, such as ekements, attributes and text nodes. If a node is an ekement node it can have any number if child nodes. These child nodes can be accessed by using the subscript operator with a numerical index.

xml_node()
The default constructor creates an empty xml node.
xml_node(xml doc)
Construct a node from the XML document. The xml_node object will be the root node of the XML document.
bool is_a_node(void)
Return true if the object actually is an XML node.
xml_node operator[](int n)
Return the child node with index n.

7.3 class xml_element : xml_node

The class xml_element is derived from the class xml_node and adds properties specific to XML elements.

xml_element()
The default constructor creates an empty xml element.
xml_element(xml doc)
Construct an element from the XML document. The xml_element object will be the root element of the XML document.
std::vector<xml_element> operator[](String tagname);
Find the child elements with the specified tagname.
String attribute(String name);
Find the value of an attribute. Return an empty string is the attribute does not exist.
std::map<String, String> attributes(void);
Find all attributes of the element in a map.

8 configuration - Class for configuration parameters

#include <configuration.h> configuration config;

Handle configurational parameters for the application. Many applications need some permanently stored configurational data. The information is usually stored in two places: A system- wide configuration file and a configuration file per user. The content of the configuration file is in XML format. The configuration base class takes care of finding the configuration files, e.g. in /etc/app.conf or in /usr/local/etc/app.conf, along with the configuration file in the user's home directory. The config files are parsed with the gnome XML parser and a framework is provided to find configurational items.

8.1 Class configuration

Hold the configuration data for an application. Both the system-wide configuration and a user-specific configuration are stores in a configuration object.

configuration()
The default constructor creates an empty configuration.
read(String name)
Find the config files and parse the XML. Both the filename and the root element of the XML files must match the name. Two configuarions are read. The system and the user config. First system config in /etc and if it does not exist, in /usr/local/etc. The user config is read from the current directory. If that does not exist, try the home directory.

find_parameter(String section, String parameter, int sec_nr = 0, int param_n = 0)
Return the value of a config parameter. The parameter is obtained from the system-wide config. If the parameter is also defined in the user config, this will override the value in the system config.