Aztec® Programming Language
Version 1.1 Alpha 2

Copyright © 2010-2017, Aztec Development Group, All Rights Reserved

Download Aztec

Search        Contact Us

I've been aware of the time going by...

They say in the end... it's the wink of an eye.

- Jackson Browne

 

aztec.util.Time

public class Time from<Base>

Base

Time

The Time class provides general purpose date/time functionality. It supports creating the Time object in a variety of ways, extracting individual pieces from the object, and also supports Time addition and subtraction. It also provides a large variety of time and date formats for creating string representations of the time and date. This class works together with the TimeInterval class to provide a flexible date and time management system.

 

The TimeFormat and DateFormat enumerations defined below are provided to specify time and date string formats for writing the time into a string, and also as a guide to parse a string to extract the various time and date components.

 

public enum DateFormat

{

MMDDYY, MMDDYYYY, MonDDYY, MonDDYYYY, MonthDDYY, MonthDDYYYY,

DDMMYY, DDMMYYYY, DDMonYY, DDMonYYYY, DDMonthYY, DDMonthYYYY,

YYMMDD, YYYYMMDD, YYMonDD, YYYYMonDD, YYMonthDD, YYYYMonthDD

}

 

public enum TimeFormat

{

HHMM, HHMMSS, HHMMSSms

}

 

For date formats, MM is month (1-12), DD is day (1-31), YY is a two digit year, and YYYY is a 4 digit year (1970 - 3000). The abbreviation "Mon" is used to indicate a 3 letter month (Jan, Feb, Mar, etc.) and "Month" is used to indicate the full spelling of the month (January, February, March, etc.).

 

For time formats, HH is hours (0-23 or 1-12), MM is minutes (0-59), SS is seconds (0-59) and ms is milliseconds (0-999).

 

Conversion methods in this class which use these formatting enumerations also offer control over the delimiters, prepending zeroes to each numeric term, displaying am/pm, and using 12/24 hour time. These format specifiers are used when creating a date/time striing based on the contents of the Time object (Str(), TimeStr(), DateStr(), etc.), and they are also used as a guide when parsing a string to determine its date/time components, as is necessary in some of the Time constructor methods.

 

The following tables shows the "basic" date and time format for each of the enumeration values using an example date of August 19th, 2016 at 11:00am. Each of the date strings is shown using the default delimiters. Each method provides a lot of flexibility with altering this basic format using the various options mentioned in the previous paragraph. For example, using a delimiter string of " ," instead of the "-" default, Aug-19-2016 becomes Aug 19, 2016. In addition to the predefined time and date formats shown and the various formatting options that are supported, the Time class provides access to all of the individual date and time components, so it is easy to manually create any type of formatted date and time string necessary.

 

TimeFormat Examples

 

DateFormat Examples

 

 

Time Methods

Time() Constructor for the Time class with no args to represent current time
Time() Constructor for the Time class using seconds from 1970-01-01, with optional MilliSeconds
Time() Constructor for the Time class using Year, Month, Day, Hour, Minute, Second and MilliSeconds as integers
Time() Constructor for the Time class using another Time object
Time() Constructor for the Time class using a string and Date format specifiers
Time() Constructor for the Time class using a string and Time format specifiers
Time() Constructor for the Time class using a string and Date and Time format specifiers
TotalSeconds() Returns internal time value as seconds since 1970-01-01
SetTime() Sets a new internal time value using seconds since 1970-01-01 and number of milliseconds
IsValid() Returns true if Time object is valid (based on parameters used to create it)
Year() Returns the year component of the Time value as an integer
Month() Returns the month component of the Time value as an integer
Day() Returns the day component of the Time value as an integer
Hour() Returns the hour component of the Time value as an integer
Minute() Returns the minute component of the Time value as an integer
Second() Returns the second component of the Time value as an integer
MilliSecond() Returns the millisecond component of the Time value as an integer
DayOfWeek() Returns the "day of week" for the Time value as an integer (1-7)
Str() Returns a default string representation of Time value
MonthStr() Returns the month component of the Time value as a string
DayOfWeekStr() Returns the "day of week" for the Time value as a string
TimeStr() Returns a string representation of the Time value based on TimeFormat and other options
DateStr() Returns a string representation of the Time value based on DateFormat and other options
Add() Adds a number of seconds (and optional milliseconds) to the Time value
Add() Adds a TimeInterval object to the Time value
Sub() Subtracts a number of seconds (and optional milliseconds) from the Time value
Sub() Subtracts a TimeInterval object from the Time value
Sub() Subtracts a Time object from the Time value and returns a TimeInterval object

Derived Classes

See Also

 


Time()

public method Time()

Parameters

None

Return Value

None

Description

Constructor for the Time class. This implementation has no arguments and sets the Time object with the current time from the operating system.

 

Time Class


Time()

public method Time(int Seconds, int MilliSeconds = 0)

Parameters

Seconds

Number of seconds since 1970-01-01 (>= 0)

MilliSeconds

Number of milliseconds (0-999, 0 is default)

Return Value

None

Description

Constructor for the Time class. This implementation takes two integer arguments. The first argument represents the number of seconds since January 1st, 1970 and the second argument represents the number of milliseconds, with a default of zero. If the input values do not conform to a valid date and time, the Time object is marked as invalid.

 

Time Class


Time()

public method Time(int Year, int Month, int Day, int Hour, int Minute, int Second, int MilliSecond = 0)

Parameters

Year

Year portion of the time (1970-3000)

Month

Month portion of the time (1-12)

Day

Day portion of the time (1-31)

Hour

Hour portion of the time (0-23)

Minute

Minute portion of the time (0-59)

Second

Second portion of the time (0-59)

MilliSecond

Millisecond portion of the time (0-999)

Return Value

None

Description

Constructor for the Time class. This implementation takes seven integer arguments which represent the individual pieces of the date. If the input values do not conform to a valid date and time, the Time object is marked as invalid.

 

Time Class


Time()

public method Time(Time SourceTime)

Parameters

SourceTime

Source time used for initialization

Return Value

None

Description

Constructor for the Time class. This implementation takes a single Time argument which is used to initialize this new Time object. Once complete, this new Time object will represent the same exact time value as the incoming source Time object.

 

Time Class


Time()

public method Time(string TimeString, DateFormat DateFmtEnum, string Delimiters)

Parameters

TimeString

Input string containing the date, with contents based on value of DateFormat

DateFmtEnum

Date format enumeration

Delimiters

Delimiter character(s) to use for parsing

Return Value

None

Description

Constructor for the Time class. This implementation takes a string which contains the date (no time components). The DateFormat enumeration and delimiters are specified to help the parser determine how to break up the date string into separate date components. Any number of delimiter characters can be specified.

 

If the specified string does not conform to a valid date, the Time object is marked as invalid.

 

Time Class


Time()

public method Time(string TimeString, TimeFormat TimeFmtEnum, string Delimiters)

Parameters

TimeString

Input string containing the time, with contents based on value of TimeFormat

TimeFmtEnum

Time format enumeration

Delimiters

Delimiter character(s) to use for parsing

Return Value

None

Description

Constructor for the Time class. This implementation takes a string which contains the time (no date components). The TimeFormat enumeration and delimiters are specified to help the parser determine how to break up the time string into separate time components. Any number of delimiter characters can be specified. Since there are no date components involved in this method, the date will be set as January 1st, 1970 with the time as specified here.

 

If the specified string does not conform to a valid time, the Time object is marked as invalid.

 

Time Class


Time()

public method Time(string TimeString, DateFormat DateFmtEnum, TimeFormat TimeFmtEnum, string Delimiters)

Parameters

TimeString

Input string containing the time, with contents based on value of TimeFormat

DateFmtEnum

Date format enumeration

TimeFmtEnum

Time format enumeration

Delimiters

Delimiter character(s) to use for parsing

Return Value

None

Description

Constructor for the Time class. This implementation takes a string which contains both the date and time components. The DateFormat and TimeFormat enumerations and delimiters are specified to help the parser determine how to break up the string into separate date and time components. Any number of delimiter characters can be specified, and the list needs to contain all delimiters used for both the date and time sections of the string.

 

If the specified string does not conform to a valid date and time, the Time object is marked as invalid.

 

Time Class


TotalSeconds()

public method<int> TotalSeconds()

Parameters

None

Return Value

Internal time value in seconds since 1970-01-01

Description

This method returns the number of seconds since 1970-01-01 corresponding to the internal time value within this Time object. The Milliseconds value is not included in this result.

 

Time Class


SetTime()

public method<bool> SetTime(int Seconds, int MilliSeconds = 0)

Parameters

Seconds

Number of seconds since 1970-01-01

MilliSeconds

Number of milliseconds (0-999, 0 is default)

Return Value

Returns true if the new time/date is valid

Description

This method sets the internal time value with the number of seconds since 1970-01-01 which is passed in to the method. An additional number of milliseconds can also be passed in, with a default of zero. If the new time value is valid, the method returns true and false if not. The internal "IsValid" flag will also be set accordingly.

 

Time Class


IsValid()

public method<bool> IsValid()

Parameters

None

Return Value

Returns true if the internal time value is valid.

Description

This method returns true if the internal date value is valid and false if it is not valid.

 

Time Class


Year()

public method<int> Year()

Parameters

None

Return Value

Year portion of the time

Description

This method returns the Year portion of the Time value as an integer (valid value is in the range 1970 - 3000). If the internal Time value is invalid, this method will return zero.

 

Time Class


Month()

public method<int> Month()

Parameters

None

Return Value

Month portion of the time

Description

This method returns the Month portion of the Time value as an integer (valid value is in the range 1-12). If the internal Time value is invalid, this method will return zero.

 

Time Class


Day()

public method<int> Day()

Parameters

None

Return Value

Day portion of the time

Description

This method returns the Day portion of the Time value as an integer (valid value is in the range 1-31). If the internal Time value is invalid, this method will return zero.

 

Time Class


Hour()

public method<int> Hour()

Parameters

None

Return Value

Hour portion of the time

Description

This method returns the Hour portion of the Time value as an integer (valid value is in the range 0-23). If the internal Time value is invalid, this method will return zero.

 

Time Class


Minute()

public method<int> Minute()

Parameters

None

Return Value

Minute portion of the time

Description

This method returns the Minute portion of the Time value as an integer (valid value is in the range 0-59). If the internal Time value is invalid, this method will return zero.

 

Time Class


Second()

public method<int> Second()

Parameters

None

Return Value

Second portion of the time

Description

This method returns the Second portion of the Time value as an integer (valid value is in the range 0-59). If the internal Time value is invalid, this method will return zero.

 

Time Class


MilliSecond()

public method<int> MilliSecond()

Parameters

None

Return Value

MilliSecond portion of the time

Description

This method returns the MilliSecond portion of the Time value as an integer (valid value is in the range 0-999). If the internal Time value is invalid, this method will return zero.

 

Time Class


DayOfWeek()

public method<int> DayOfWeek()

Parameters

None

Return Value

Day of week (1-7)

Description

This method returns the day of the week corresponding to the internal Time value as an integer in the range 1-7 (Sunday-Saturday).

 

Time Class


Str()

public method<string> Str()

Parameters

None

Return Value

Time as a string

Description

This method returns the time based on the specified format string. The default string is "YYYY-MM-DD HH:MM:SS".

 

Time Class


MonthStr()

public virtual method<string> MonthStr(bool UseFullName = true)

Parameters

UseFullName

Flag indiactes to use full name or short name

Return Value

Month as a string

Description

This method returns the month corresponding to the internal Time value as a string. If the UseFullName flag is true, the months are in the form "January", "February", etc. If the flag is false, the days are in the form "Jan", "Feb", etc. (all short names are 3 characters in length).

 

Time Class


DayOfWeekStr()

public virtual method<string> DayOfWeekStr(bool UseFullName = true)

Parameters

UseFullName

Flag indiactes to use full name or short name

Return Value

Day of week as a string

Description

This method returns the day of the week corresponding to the internal Time value as a string. If the UseFullName flag is true, the days are in the form "Monday", "Tuesday", etc. If the flag is false, the days are in the form "Mon", "Tue", etc. (all short names are 3 characters in length).

 

Time Class


TimeStr()

public virtual method<string> TimeStr(TimeFormat TimeFmtEnum, string Delimiters = "::.", bool PrependZeroes = true, bool UseAmPm = true, bool Use24Hours = false)

Parameters

TimeFmtEnum

TimeFormat enumeration to drive format of string

Delimiters

String containing delimiter character(s)

PrependZeroes

Each piece of the time will be "left padded" with zero to max size

UseAmPm

Adds "am" or "pm" to the time as appropriate if set

Use24Hours

Uses 24 hour (military) time format if set

Return Value

Formatted time string

Description

This method returns a formatted time string based on the TimeFmtEnum value passed in, together with delimiters and the three flags that are passed in. Samples of the output for the three separate TimeFormat enumeration values are shown in the table at the top of this page.

 

The Delimiters string works a bit differently than the delimiter string used for parsing a time/date string as in several of the Time() constructors. For parsing, the delimiter string is a simple list of all valid delimiter characters, regardless of their position in the string. For this string formatting method, the position of a character in the delimiter string affects how it is used. For a time string containing 4 terms, hour, minute, second and millsecond, there are three "spaces" in between those components. So the space between the seconds and millseconds terms will be filled with the third delimiter character in the string, as an example. If less than three characters, the last delimiter character in the string will be used.

 

The other boolean arguments provide the programmer with further control over the appearance of the string. Note that if the the "Use24Hours" flag is set, the "UseAmPm" flag will be forced to false and "PrependZeroes" will be forced to true. In addition, no delimiter will be used between the hour and minute components of the time.

 

Time Class


DateStr()

public virtual method<string> DateStr(DateFormat DateFmtEnum, string Delimiters = "-", bool PrependZeroes = true)

Parameters

DateFmtEnum

DateFormat enumeration to drive format of string

Delimiters

String containing delimiter character(s)

PrependZeroes

Each piece of the date will be "left padded" with zero to max size

Return Value

Formatted date string

Description

This method returns a formatted date string based on the DateFmtEnum value passed in, together with delimiters and the "PrependZeroes" flag that are passed in. Samples of the output for the eighteen separate DateFormat enumeration values are shown in the table at the top of this page.

 

The Delimiters string works a bit differently than the delimiter string used for parsing a time/date string as in several of the Time() constructors. For parsing, the delimiter string is a simple list of all valid delimiter characters, regardless of their position in the string. For this string formatting method, the position of a character in the delimiter string affects how it is used. For a date string containing 3 terms, year, month and day, there are two "spaces" in between those components. So the space between the month and day terms will be filled with the second delimiter character in the string, for example. If less than two characters, the last delimiter character in the string will be used.

 

Time Class


Add()

public method<bool> Add(int Seconds, int MilliSeconds = 0)

Parameters

Seconds

Number of seconds to be added

MilliSeconds

Number of milliseconds to be added

Return Value

True if success

Description

This method adds the number of seconds (and optional milliseconds) to the internal Time value. The method returns true if successful and false if not.

 

Time Class


Add()

public method<bool> Add(TimeInterval Interval)

Parameters

Interval

Time interval to be added

Return Value

True if success

Description

This method adds the TimeInternal value to the internal Time value. The method returns true if successful and false if not.

 

Time Class


Sub()

public method<bool> Sub(int Seconds, int MilliSeconds = 0)

Parameters

Seconds

Number of seconds to be subtracted

MilliSeconds

Number of milliseconds to be subtracted

Return Value

True if success

Description

This method subtracts the number of seconds (and optional milliseconds) from the internal Time value. The method returns true if successful and false if not.

 

Time Class


Sub()

public method<bool> Sub(TimeInterval Interval)

Parameters

Interval

Time interval to be subtracted

Return Value

True if success

Description

This method subtracts the TimeInternal value from the internal Time value. The method returns true if successful and false if not.

 

Time Class


Sub()

public method<TimeInterval> shared Sub(Time SourceTime1, Time SourceTime2)

Parameters

SourceTime1

Starting Time value

SourceTime2

Time value to be subtracted from SourceTime1

Return Value

TimeInterval representing amount of time between the two times

Description

This shared method subtracts SourceTime2 from SourceTime1 and returns a TimeInterval object representing the difference between the two times. This TimeInterval object can represent a positive time difference or a negative time difference.

 

Time Class

 

Copyright © 2010-2017

Aztec Development Group

All Rights Reserved

Download Aztec