DateString
Unit functions
You're viewing an older version of this page (#340). View the current version.
Interface
#include <codecogs/units/date/datestring.h>
using namespace Units::Date;
DateString(int initialSize);void fill(const char* format, DateTime& dt, Units::Time::summerTimeRegion region);int m_length;int m_maxLength;char *m_pStr;bool resize(int newLength);bool resizeIfNecessary(int numCharsToBeAdded);void append(int numToAppend, int minLength = 0);void append(char pChrToAppend);void append(double numToAppend, int minLength = 0);void append(const char* pStrToAppend, int maxLength = -1);DateString::DateString(int initialSize)void DateString::trim()void DateString::end()char* DateString::getString()void DateString::fill(const char* format, DateTime& dt, Units::Time::summerTimeRegion region )bool DateString::resize(int newLength)bool DateString::resizeIfNecessary(int numCharsToBeAdded)void DateString::append(double numToAppend, int minLength)void DateString::append(int numToAppend, int minLength)void DateString::append(const char* pStrToAppend, int maxLength)void DateString::append(char pChrToAppend)
Overview
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.
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;Members of DateString
CLASS METHOD
DateString
CLASS METHOD
fill
CLASS MEMBER
m_length
The length in characters of the string (the index of the NULL character). It is always less than m_maxLength
CLASS MEMBER
m_maxLength
The maximum number of characters (including the NULL character) that can be inserted
CLASS MEMBER
m_pStr
The character buffer
CLASS METHOD
resize
CLASS METHOD
resizeIfNecessary
CLASS METHOD
append
CLASS METHOD
append
CLASS METHOD
append
CLASS METHOD
append
CLASS METHOD
DateString
Keith Athaide
CLASS METHOD
trim
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.
Keith Athaide
CLASS METHOD
end
Call this function before the string is to be displayed or processed.
Keith Athaide
CLASS METHOD
getString
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
Keith Athaide
CLASS METHOD
fill
Fills the string based on the given format, date and region
For convenience, the format characters have been arranged by category.
| Option | Description | Examples |
| L | Whether it's a leap year. | \c 1 if it is a leap year, \c 0 otherwise. |
| Y | A full numeric representation of a year, 4 digits. If needed, \c BC will be suffixed. | \c 4713BC, \c 1999, \c 2005 |
| y | A two digit representation of a year. If needed, \c BC will be suffixed. | \c 13BC, \c 99 or \c 05 |
| Option | Description | Examples |
| F | A full textual representation of a month. | \c Jan through \c Dec |
| m | Numeric representation of a month, with leading zeros. | \c 01 through \c 12 |
| M | A short textual representation of a month consisting of three letters. | \c Jan through \c Dec |
| n | Numeric representation of a month, without leading zeros. | \c 1 through \c 12 |
| t | Number of days in the given month. | \c 28 through \c 31 |
| Option | Description | Examples |
| d | Day of the month, 2 digits with leading zeros. | \c 01 through \c 31 |
| j | Day of the month without leading zeros. | \c 1 through \c 31 |
| S | English ordinal suffix for the day of the month, 2 characters. Works well with j | \c st, \c nd, \c rd or \c th |
| z | The day of the year (starting from 0). | \c 0 through \c 365 |
| Option | Description | Examples |
| D | A textual representation of a day, three letters. | \c Sun through \c Sat |
| l (lowercase 'L') | A full textual representation of the day of the week. | \c Sunday through \c Saturday |
| w | Numeric representation of the day of the week. | \c 0 (for Sunday) through \c 6 (for Saturday) |
| W | ISO-8601 week number of year, weeks starting on Monday. | \c 42 |
| Option | Description | Examples |
| a | Lowercase Ante meridiem and Post meridiem | \c am or \c pm |
| A | Uppercase Ante meridiem and Post meridiem | \c AM or \c PM |
| B | Swatch Internet time | \c 000 through \c 999 |
| g | 12-hour format of an hour without leading zeros. | \c 1 through \c 12 |
| G | 24-hour format of an hour without leading zeros. | \c 0 through \c 23 |
| h | 12-hour format of an hour with leading zeros | \c 01 through \c 12 |
| H | 24-hour format of an hour with leading zeros. | \c 00 through \c 23 |
| i | Minutes with leading zeros. | \c 00 to \c 59 |
| s | Seconds, with leading zeros. | \c 00 through \c 59 |
| U | Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT) | \c 1112053296 |
| Option | Description | Examples |
| I (uppercase 'i') | Whether or not the date is in daylights savings time. | \c 1 if Daylight Savings Time, \c 0 otherwise. |
| O | Difference to Greenwich time (GMT) in hours. | \c +0200 , \c -1300 |
| T | Timezone setting of this machine. | \c EST, \c 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. | \c -43200 through \c 43200 |
| 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
Keith Athaide
CLASS METHOD
resize
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 otherwiseKeith Athaide
CLASS METHOD
resizeIfNecessary
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 otherwiseKeith Athaide
CLASS METHOD
append
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 '-' character is prefixed. No prefix is inserted for a positive number.
Parameters
Keith Athaide
CLASS METHOD
append
If a negative number is supplied, a '-' character is prefixed. No prefix is inserted for a positive number.
Parameters
Keith Athaide
CLASS METHOD
append
Parameters
Keith Athaide
CLASS METHOD
append
Parameters
Keith Athaide