Unit functions

Contents

Interface Function Documentation Class Documentation Page Comments

Interface

#include <codecogs/units/date/datestring.h>

using namespace Units::Date;

		class DateString A class that represents a string built up from a specific date and time [constructor] DateString void trim void end char* getString void fill int m_length The length in characters of the string (the index of the NULL character). It is always less than m_maxLength int m_maxLength The maximum number of characters (including the NULL character) that can be inserted char* m_pStr The character buffer bool resize bool resizeIfNecessary void append void append void append void append
	DateString::DateString	unknown (int initialSize) Constructs an object of this class with the character buffer having the specified size
	void	DateString::trim () Resizes the character buffer so that is just large enough to accomodate all inserted characters and a NULL character (which is inserted).
	void	DateString::end () Inserts a NULL character at the end of the string.
	char*	DateString::getString () Gets a pointer to the string
	void	DateString::fill (const char* format, DateTime& dt, Units::Time::summerTimeRegion region) Fills the string based on the given format, date and region
	bool	DateString::resize (int newLength) Resizes the character buffer to be of the size 'newLength', preserving its previous contents
	bool	DateString::resizeIfNecessary (int numCharsToBeAdded) Resizes the character buffer if required.
	void	DateString::append (double numToAppend, int minLength) Appends an integer with the specified minimum number of digits
	void	DateString::append (int numToAppend, int minLength) Appends an integer with the specified number of digits
	void	DateString::append (const char* pStrToAppend, int maxLength) Appends a string, appending all the characters or only &*#039;maxLength&*#039; number of characters
	void	DateString::append (char pChrToAppend) Appends a character

Class Documentation

This class exposes methods that make it easy to append characters, normal integers, large integers as doubles (fractional part is discarded) and strings to a single string.

The Format String

Some of the characters in the format string are considered special and will be replaced as specified by the tables below. If a character not in the tables is used, it will be used verbatim.

If one of the format characters is required to be used verbatim, it must be escaped with a backslash. Note that the backslash itself will have to be escaped with another backslash. So the character will have two backslashes in front of it in source code. Examples follow after the tables of format characters.

Format String Examples

The format strings are given as seen in source code

Format string	Result
"l"	Monday
"l dS of F Y h:i:s A"	Monday 28th of March 2005 02:25:22 PM
"l \t\h\e jS"	Monday the 28th
"F j, Y, g:i a"	March 29, 2005, 1:19 am
"m.d.y"	03.29.05
"j, n, Y"	29, 3, 2005
"Ymd"	20050329
"h-i-s, j-m-y, it is w Day z"	01-21-55, 29-03-05, 2131 2155 2 Tueam05 87
"\i\t \i\s \t\h\e jS \d\a\y."	it is the 29th day.
"D M j G:i:s T Y"	Tue Mar 29 1:24:52 GMT Daylight Time 2005
"H:m:s \m \i\s\ \m\o\n\t\h"	01:03:15 m is month
"H:i:s"	01:25:40

None of the append functions affix a NULL character to the end of the string as it is expected that multiple append calls will be made at a time before the string is displayed and hence it is unnecessary to add a NULL each time a new entity is appended.

Warning:

The memory dynamically allocated to the enclosed string is never freed by the class and must be freed by external code. This can be done with a statement such as:

delete[] dateString.getString();

Example 1:

DateTime dt;
DateString dateString(20);  // initialise with space for 20 characters
 
// Fill dateString with a specific date and time
dateString.fill("h:i:s, jS F Y", dt, Units::Time::st_None);
dateString.trim();
char* pStr = dateString.getString();
 
cout<<pStr;
 
delete[] pStr;

Authors:

Keith Athaide

It is recommended that repeated calls not be made to this function. This function should only be called just before the built up string is to be processed by external code.

Authors:

Keith Athaide

Call this function before the string is to be displayed or processed.

Authors:

Keith Athaide

Unless the function end() were called, the returned string will not be NULL terminated.

The returned pointer should not be stored so as to always pointed to the formatted string, as successive calls to fill() or to trim() could cause the pointer to become invalid.

Returns:

The date string

Authors:

Keith Athaide

Fills the string based on the given format, date and region

For convenience, the format characters have been arranged by category.

Year format specifiers

Option	Description	Examples
L	Whether it's a leap year.	1 if it is a leap year, 0 otherwise.
Y	A full numeric representation of a year, 4 digits. If needed, BC will be suffixed.	4713BC, 1999, 2005
y	A two digit representation of a year. If needed, BC will be suffixed.	13BC, 99 or 05

Month format specifiers

Option	Description	Examples
F	A full textual representation of a month.	Jan through Dec
m	Numeric representation of a month, with leading zeros.	01 through 12
M	A short textual representation of a month consisting of three letters.	Jan through Dec
n	Numeric representation of a month, without leading zeros.	1 through 12
t	Number of days in the given month.	28 through 31

Day format specifiers

Option	Description	Examples
d	Day of the month, 2 digits with leading zeros.	01 through 31
j	Day of the month without leading zeros.	1 through 31
S	English ordinal suffix for the day of the month, 2 characters. Works well with j	st, nd, rd or th
z	The day of the year (starting from 0).	0 through 365

Week format specifiers

Option	Description	Examples
D	A textual representation of a day, three letters.	Sun through Sat
l (lowercase 'L')	A full textual representation of the day of the week.	Sunday through Saturday
w	Numeric representation of the day of the week.	0 (for Sunday) through 6 (for Saturday)
W	ISO-8601 week number of year, weeks starting on Monday.	42

Time format specifiers

Option	Description	Examples
a	Lowercase Ante meridiem and Post meridiem	am or pm
A	Uppercase Ante meridiem and Post meridiem	AM or PM
B	Swatch Internet time	000 through 999
g	12-hour format of an hour without leading zeros.	1 through 12
G	24-hour format of an hour without leading zeros.	0 through 23
h	12-hour format of an hour with leading zeros	01 through 12
H	24-hour format of an hour with leading zeros.	00 through 23
i	Minutes with leading zeros.	00 to 59
s	Seconds, with leading zeros.	00 through 59
U	Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT)	1112053296

Timezone related specifiers

Option	Description	Examples
I (uppercase 'i')	Whether or not the date is in daylights savings time.	1 if Daylight Savings Time, 0 otherwise.
O	Difference to Greenwich time (GMT) in hours.	+0200 , -1300
T	Timezone setting of this machine.	EST, MDT
Z	Timezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive.	-43200 through 43200

Standard format specifiers

Option	Description	Examples
c	ISO 8601 date	2005-03-29T00:47:51+0100
r	RFC 2822 formatted date	Tue, 29 Mar 2005 00:47:51 +0100

Parameters:

format	Constant
dt	[in] The date and time to use
region	[in] The current region

Authors:

Keith Athaide

The member m_maxLength is automatically updated by this function to reflect the new size.

Returns:

true if the character buffer was successfully resized, false otherwise

Authors:

Keith Athaide

Checks the length of the character buffer and ensures that 'numCharsToBeAdded' plus the NULL character can be inserted into the character buffer. If the character buffer is not large enough, it is resized to twice its size.

Returns:

true if the character buffer is large enough, false otherwise

Authors:

Keith Athaide

This function accepts a double only to get numbers greater than a 32 bit integer can provide. The fractional part of the passed number is discarded.

If a negative number is supplied, a &*#039;-&*#039; character is prefixed. No prefix is inserted for a positive number.

Parameters:

numToAppend	Numerical number to append
minLength	Minimum length to make the number, by padding with zeros.

Authors:

Keith Athaide

If a negative number is supplied, a &*#039;-&*#039; character is prefixed. No prefix is inserted for a positive number.

Parameters:

numToAppend	Numerical number to append
minLength	Minimum length to make the number, by padding with zeros.

Authors:

Keith Athaide

Parameters:

pStrToAppend	Pointer to the string to be appended
maxLength	Make number of character from pStrToAppend to copy to the formatted string

Authors:

Keith Athaide

Parameters:

pChrToAppend

Character to append to the string

Authors:

Keith Athaide

Function Documentation

Authors:

Keith Athaide