/usr/include/glibmm-2.4/glibmm/datetime.h is in libglibmm-2.4-dev 2.42.0-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 | // -*- c++ -*-
// Generated by gmmproc 2.42.0 -- DO NOT MODIFY!
#ifndef _GLIBMM_DATETIME_H
#define _GLIBMM_DATETIME_H
/* Copyright (C) 2011 The glibmm Development Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free
* Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/
#include <glibmmconfig.h>
#include <glibmm/refptr.h>
#include <glibmm/ustring.h>
#include <glib.h>
#ifndef DOXYGEN_SHOULD_SKIP_THIS
typedef struct _GDateTime GDateTime;
#endif
namespace Glib
{
struct TimeVal;
class TimeZone;
/** A value representing an interval of time, in microseconds. As GTimeSpan,
* its underlying type is gint64.
*/
typedef GTimeSpan TimeSpan;
/** DateTime - A structure representing Date and Time.
* DateTime is a structure that combines a Gregorian date and time into a
* single structure. It provides many conversion and methods to manipulate
* dates and times. Time precision is provided down to microseconds and the
* time can range (proleptically) from 0001-01-01 00:00:00 to 9999-12-31
* 23:59:59.999999. DateTime follows POSIX time in the sense that it is
* oblivious to leap seconds.
*
* DateTime is an immutable object; once it has been created it cannot be
* modified further. All modifiers will create a new DateTime. Nearly all such
* functions can fail due to the date or time going out of range, in which case
* <tt>0</tt> will be returned.
*
* DateTime is reference counted. When the reference count drops to 0, the
* resources allocated by the DateTime structure are released.
*
* Many parts of the API may produce non-obvious results. As an example, adding
* two months to January 31st will yield March 31st whereas adding one month
* and then one month again will yield either March 28th or March 29th. Also
* note that adding 24 hours is not always the same as adding one day (since
* days containing daylight savings time transitions are either 23 or 25 hours
* in length).
* @newin{2,30}
*/
class DateTime
{
public:
#ifndef DOXYGEN_SHOULD_SKIP_THIS
typedef DateTime CppObjectType;
typedef GDateTime BaseObjectType;
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
/** Constructs an invalid object.
* E.g. for output arguments to methods. There is not much you can do with
* the object before it has been assigned a valid value.
*/
DateTime();
// Use make_a_copy=true when getting it directly from a struct.
explicit DateTime(GDateTime* castitem, bool make_a_copy = false);
DateTime(const DateTime& src);
DateTime& operator=(const DateTime& src);
~DateTime();
GDateTime* gobj() { return gobject_; }
const GDateTime* gobj() const { return gobject_; }
///Provides access to the underlying C instance. The caller is responsible for freeing it. Use when directly setting fields in structs.
GDateTime* gobj_copy() const;
protected:
GDateTime* gobject_;
private:
public:
/** Creates a DateTime corresponding to this exact instant in the given
* time zone @a tz. The time is as accurate as the system allows, to a
* maximum accuracy of 1 microsecond.
*
* This function will always succeed unless the system clock is set to
* truly insane values (or unless GLib is still being used after the
* year 9999).
*
* You should release the return value by calling g_date_time_unref()
* when you are done with it.
*
* @newin{2,26}
*
* @param tz A TimeZone.
* @return A new DateTime, or <tt>0</tt>.
*/
static DateTime create_now(const TimeZone& tz);
/** Creates a DateTime corresponding to this exact instant in the local
* time zone.
*
* This is equivalent to calling g_date_time_new_now() with the time
* zone returned by g_time_zone_new_local().
*
* @newin{2,26}
*
* @return A new DateTime, or <tt>0</tt>.
*/
static DateTime create_now_local();
/** Creates a DateTime corresponding to this exact instant in UTC.
*
* This is equivalent to calling g_date_time_new_now() with the time
* zone returned by g_time_zone_new_utc().
*
* @newin{2,26}
*
* @return A new DateTime, or <tt>0</tt>.
*/
static DateTime create_now_utc();
/** Creates a DateTime corresponding to the given Unix time @a t in the
* local time zone.
*
* Unix time is the number of seconds that have elapsed since 1970-01-01
* 00:00:00 UTC, regardless of the local time offset.
*
* This call can fail (returning <tt>0</tt>) if @a t represents a time outside
* of the supported range of DateTime.
*
* You should release the return value by calling g_date_time_unref()
* when you are done with it.
*
* @newin{2,26}
*
* @param t The Unix time.
* @return A new DateTime, or <tt>0</tt>.
*/
static DateTime create_now_local(gint64 t);
/** Creates a DateTime corresponding to the given Unix time @a t in UTC.
*
* Unix time is the number of seconds that have elapsed since 1970-01-01
* 00:00:00 UTC.
*
* This call can fail (returning <tt>0</tt>) if @a t represents a time outside
* of the supported range of DateTime.
*
* You should release the return value by calling g_date_time_unref()
* when you are done with it.
*
* @newin{2,26}
*
* @param t The Unix time.
* @return A new DateTime, or <tt>0</tt>.
*/
static DateTime create_now_utc(gint64 t);
/** Creates a DateTime corresponding to the given TimeVal @a tv in the
* local time zone.
*
* The time contained in a TimeVal is always stored in the form of
* seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the
* local time offset.
*
* This call can fail (returning <tt>0</tt>) if @a tv represents a time outside
* of the supported range of DateTime.
*
* You should release the return value by calling g_date_time_unref()
* when you are done with it.
*
* @newin{2,26}
*
* @param tv A TimeVal.
* @return A new DateTime, or <tt>0</tt>.
*/
static DateTime create_now_local(const TimeVal& tv);
/** Creates a DateTime corresponding to the given TimeVal @a tv in UTC.
*
* The time contained in a TimeVal is always stored in the form of
* seconds elapsed since 1970-01-01 00:00:00 UTC.
*
* This call can fail (returning <tt>0</tt>) if @a tv represents a time outside
* of the supported range of DateTime.
*
* You should release the return value by calling g_date_time_unref()
* when you are done with it.
*
* @newin{2,26}
*
* @param tv A TimeVal.
* @return A new DateTime, or <tt>0</tt>.
*/
static DateTime create_now_utc(const TimeVal& tv);
/** Creates a new DateTime corresponding to the given date and time in
* the time zone @a tz.
*
* The @a year must be between 1 and 9999, @a month between 1 and 12 and @a day
* between 1 and 28, 29, 30 or 31 depending on the month and the year.
*
* @a hour must be between 0 and 23 and @a minute must be between 0 and 59.
*
* @a seconds must be at least 0.0 and must be strictly less than 60.0.
* It will be rounded down to the nearest microsecond.
*
* If the given time is not representable in the given time zone (for
* example, 02:30 on March 14th 2010 in Toronto, due to daylight savings
* time) then the time will be rounded up to the nearest existing time
* (in this case, 03:00). If this matters to you then you should verify
* the return value for containing the same as the numbers you gave.
*
* In the case that the given time is ambiguous in the given time zone
* (for example, 01:30 on November 7th 2010 in Toronto, due to daylight
* savings time) then the time falling within standard (ie:
* non-daylight) time is taken.
*
* It not considered a programmer error for the values to this function
* to be out of range, but in the case that they are, the function will
* return <tt>0</tt>.
*
* You should release the return value by calling g_date_time_unref()
* when you are done with it.
*
* @newin{2,26}
*
* @param tz A TimeZone.
* @param year The year component of the date.
* @param month The month component of the date.
* @param day The day component of the date.
* @param hour The hour component of the date.
* @param minute The minute component of the date.
* @param seconds The number of seconds past the minute.
* @return A new DateTime, or <tt>0</tt>.
*/
static DateTime create(const TimeZone& tz, int year, int month, int day, int hour, int minute, double seconds);
/** Creates a new DateTime corresponding to the given date and time in
* the local time zone.
*
* This call is equivalent to calling g_date_time_new() with the time
* zone returned by g_time_zone_new_local().
*
* @newin{2,26}
*
* @param year The year component of the date.
* @param month The month component of the date.
* @param day The day component of the date.
* @param hour The hour component of the date.
* @param minute The minute component of the date.
* @param seconds The number of seconds past the minute.
* @return A DateTime, or <tt>0</tt>.
*/
static DateTime create_local(int year, int month, int day, int hour, int minute, double seconds);
/** Creates a new DateTime corresponding to the given date and time in
* UTC.
*
* This call is equivalent to calling g_date_time_new() with the time
* zone returned by g_time_zone_new_utc().
*
* @newin{2,26}
*
* @param year The year component of the date.
* @param month The month component of the date.
* @param day The day component of the date.
* @param hour The hour component of the date.
* @param minute The minute component of the date.
* @param seconds The number of seconds past the minute.
* @return A DateTime, or <tt>0</tt>.
*/
static DateTime create_utc(int year, int month, int day, int hour, int minute, double seconds);
/** Creates a copy of @a datetime and adds the specified timespan to the copy.
*
* @newin{2,26}
*
* @param timespan A TimeSpan.
* @return The newly created DateTime which should be freed with
* g_date_time_unref().
*/
DateTime add(TimeSpan timespan) const;
/** Creates a copy of @a datetime and adds the specified number of years to the
* copy. Add negative values to subtract years.
*
* @newin{2,26}
*
* @param years The number of years.
* @return The newly created DateTime which should be freed with
* g_date_time_unref().
*/
DateTime add_years(int years) const;
/** Creates a copy of @a datetime and adds the specified number of months to the
* copy. Add negative values to subtract months.
*
* @newin{2,26}
*
* @param months The number of months.
* @return The newly created DateTime which should be freed with
* g_date_time_unref().
*/
DateTime add_months(int months) const;
/** Creates a copy of @a datetime and adds the specified number of weeks to the
* copy. Add negative values to subtract weeks.
*
* @newin{2,26}
*
* @param weeks The number of weeks.
* @return The newly created DateTime which should be freed with
* g_date_time_unref().
*/
DateTime add_weeks(int weeks) const;
/** Creates a copy of @a datetime and adds the specified number of days to the
* copy. Add negative values to subtract days.
*
* @newin{2,26}
*
* @param days The number of days.
* @return The newly created DateTime which should be freed with
* g_date_time_unref().
*/
DateTime add_days(int days) const;
/** Creates a copy of @a datetime and adds the specified number of hours.
* Add negative values to subtract hours.
*
* @newin{2,26}
*
* @param hours The number of hours to add.
* @return The newly created DateTime which should be freed with
* g_date_time_unref().
*/
DateTime add_hours(int hours) const;
/** Creates a copy of @a datetime adding the specified number of minutes.
* Add negative values to subtract minutes.
*
* @newin{2,26}
*
* @param minutes The number of minutes to add.
* @return The newly created DateTime which should be freed with
* g_date_time_unref().
*/
DateTime add_minutes(int minutes) const;
/** Creates a copy of @a datetime and adds the specified number of seconds.
* Add negative values to subtract seconds.
*
* @newin{2,26}
*
* @param seconds The number of seconds to add.
* @return The newly created DateTime which should be freed with
* g_date_time_unref().
*/
DateTime add_seconds(double seconds) const;
/** Creates a new DateTime adding the specified values to the current date and
* time in @a datetime. Add negative values to subtract.
*
* @newin{2,26}
*
* @param years The number of years to add.
* @param months The number of months to add.
* @param days The number of days to add.
* @param hours The number of hours to add.
* @param minutes The number of minutes to add.
* @param seconds The number of seconds to add.
* @return The newly created DateTime that should be freed with
* g_date_time_unref().
*/
DateTime add_full(int years, int months, int days, int hours, int minutes, double seconds) const;
/** Calculates the difference in time between @a *this and @a other. The
* TimeSpan that is returned is effectively @a *this - @a other.
*
* @newin{2,26}
* @param other The other DateTime.
* @return The difference between the two DateTime, as a time
* span expressed in microseconds.
*/
TimeSpan difference(const DateTime& other) const;
/** A comparison function for DateTimes that is suitable
* as a CompareFunc.
*
* @newin{2,26}
* @param other The DateTime to compare with.
* @return -1, 0 or 1 if @a *this is less than, equal to or greater
* than @a other.
*/
int compare(const DateTime& other) const;
/** Hashes @a datetime into a <tt>unsigned int</tt>, suitable for use within HashTable.
*
* @newin{2,26}
*
* @param datetime A DateTime.
* @return A <tt>unsigned int</tt> containing the hash.
*/
guint hash() const;
/** Checks to see if @a *this and @a other are equal.
*
* Equal here means that they represent the same moment after converting
* them to the same time zone.
*
* @newin{2,26}
* @param other The DateTime to compare with.
* @return <tt>true</tt> if @a *this and @a other are equal.
*/
bool equal(const DateTime& other) const;
/** Retrieves the Gregorian day, month, and year of a given DateTime.
*
* @newin{2,26}
*
* @param year The return location for the gregorian year, or <tt>0</tt>.
* @param month The return location for the month of the year, or <tt>0</tt>.
* @param day The return location for the day of the month, or <tt>0</tt>.
*/
void get_ymd(int& year, int& month, int& day) const;
/** Retrieves the year represented by @a datetime in the Gregorian calendar.
*
* @newin{2,26}
*
* @return The year represented by @a datetime.
*/
int get_year() const;
/** Retrieves the month of the year represented by @a datetime in the Gregorian
* calendar.
*
* @newin{2,26}
*
* @return The month represented by @a datetime.
*/
int get_month() const;
/** Retrieves the day of the month represented by @a datetime in the gregorian
* calendar.
*
* @newin{2,26}
*
* @return The day of the month.
*/
int get_day_of_month() const;
/** Returns the ISO 8601 week-numbering year in which the week containing
* @a datetime falls.
*
* This function, taken together with g_date_time_get_week_of_year() and
* g_date_time_get_day_of_week() can be used to determine the full ISO
* week date on which @a datetime falls.
*
* This is usually equal to the normal Gregorian year (as returned by
* g_date_time_get_year()), except as detailed below:
*
* For Thursday, the week-numbering year is always equal to the usual
* calendar year. For other days, the number is such that every day
* within a complete week (Monday to Sunday) is contained within the
* same week-numbering year.
*
* For Monday, Tuesday and Wednesday occurring near the end of the year,
* this may mean that the week-numbering year is one greater than the
* calendar year (so that these days have the same week-numbering year
* as the Thursday occurring early in the next year).
*
* For Friday, Saturaday and Sunday occurring near the start of the year,
* this may mean that the week-numbering year is one less than the
* calendar year (so that these days have the same week-numbering year
* as the Thursday occurring late in the previous year).
*
* An equivalent description is that the week-numbering year is equal to
* the calendar year containing the majority of the days in the current
* week (Monday to Sunday).
*
* Note that January 1 0001 in the proleptic Gregorian calendar is a
* Monday, so this function never returns 0.
*
* @newin{2,26}
*
* @return The ISO 8601 week-numbering year for @a datetime.
*/
int get_week_numbering_year() const;
/** Returns the ISO 8601 week number for the week containing @a datetime.
* The ISO 8601 week number is the same for every day of the week (from
* Moday through Sunday). That can produce some unusual results
* (described below).
*
* The first week of the year is week 1. This is the week that contains
* the first Thursday of the year. Equivalently, this is the first week
* that has more than 4 of its days falling within the calendar year.
*
* The value 0 is never returned by this function. Days contained
* within a year but occurring before the first ISO 8601 week of that
* year are considered as being contained in the last week of the
* previous year. Similarly, the final days of a calendar year may be
* considered as being part of the first ISO 8601 week of the next year
* if 4 or more days of that week are contained within the new year.
*
* @newin{2,26}
*
* @return The ISO 8601 week number for @a datetime.
*/
int get_week_of_year() const;
/** Retrieves the ISO 8601 day of the week on which @a datetime falls (1 is
* Monday, 2 is Tuesday... 7 is Sunday).
*
* @newin{2,26}
*
* @return The day of the week.
*/
int get_day_of_week() const;
/** Retrieves the day of the year represented by @a datetime in the Gregorian
* calendar.
*
* @newin{2,26}
*
* @return The day of the year.
*/
int get_day_of_year() const;
/** Retrieves the hour of the day represented by @a datetime
*
* @newin{2,26}
*
* @return The hour of the day.
*/
int get_hour() const;
/** Retrieves the minute of the hour represented by @a datetime
*
* @newin{2,26}
*
* @return The minute of the hour.
*/
int get_minute() const;
/** Retrieves the second of the minute represented by @a datetime
*
* @newin{2,26}
*
* @return The second represented by @a datetime.
*/
int get_second() const;
/** Retrieves the microsecond of the date represented by @a datetime
*
* @newin{2,26}
*
* @return The microsecond of the second.
*/
int get_microsecond() const;
/** Retrieves the number of seconds since the start of the last minute,
* including the fractional part.
*
* @newin{2,26}
*
* @return The number of seconds.
*/
double get_seconds() const;
/** Gives the Unix time corresponding to @a datetime, rounding down to the
* nearest second.
*
* Unix time is the number of seconds that have elapsed since 1970-01-01
* 00:00:00 UTC, regardless of the time zone associated with @a datetime.
*
* @newin{2,26}
*
* @return The Unix time corresponding to @a datetime.
*/
gint64 to_unix() const;
/** Stores the instant in time that @a datetime represents into @a tv.
*
* The time contained in a TimeVal is always stored in the form of
* seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the time
* zone associated with @a datetime.
*
* On systems where 'long' is 32bit (ie: all 32bit systems and all
* Windows systems), a TimeVal is incapable of storing the entire
* range of values that DateTime is capable of expressing. On those
* systems, this function returns <tt>false</tt> to indicate that the time is
* out of range.
*
* On systems where 'long' is 64bit, this function never fails.
*
* @newin{2,26}
*
* @param tv A TimeVal to modify.
* @return <tt>true</tt> if successful, else <tt>false</tt>.
*/
bool to_timeval(TimeVal& tv) const;
/** Determines the offset to UTC in effect at the time and in the time
* zone of @a datetime.
*
* The offset is the number of microseconds that you add to UTC time to
* arrive at local time for the time zone (ie: negative numbers for time
* zones west of GMT, positive numbers for east).
*
* If @a datetime represents UTC time, then the offset is always zero.
*
* @newin{2,26}
*
* @return The number of microseconds that should be added to UTC to
* get the local time.
*/
TimeSpan get_utc_offset() const;
/** Determines the time zone abbreviation to be used at the time and in
* the time zone of @a datetime.
*
* For example, in Toronto this is currently "EST" during the winter
* months and "EDT" during the summer months when daylight savings
* time is in effect.
*
* @newin{2,26}
*
* @return The time zone abbreviation. The returned
* string is owned by the DateTime and it should not be
* modified or freed.
*/
Glib::ustring get_timezone_abbreviation() const;
/** Determines if daylight savings time is in effect at the time and in
* the time zone of @a datetime.
*
* @newin{2,26}
*
* @return <tt>true</tt> if daylight savings time is in effect.
*/
bool is_daylight_savings() const;
/** Create a new DateTime corresponding to the same instant in time as
* @a datetime, but in the time zone @a tz.
*
* This call can fail in the case that the time goes out of bounds. For
* example, converting 0001-01-01 00:00:00 UTC to a time zone west of
* Greenwich will fail (due to the year 0 being out of range).
*
* You should release the return value by calling g_date_time_unref()
* when you are done with it.
*
* @newin{2,26}
*
* @param tz The new TimeZone.
* @return A new DateTime, or <tt>0</tt>.
*/
DateTime to_timezone(const TimeZone& tz) const;
/** Creates a new DateTime corresponding to the same instant in time as
* @a datetime, but in the local time zone.
*
* This call is equivalent to calling g_date_time_to_timezone() with the
* time zone returned by g_time_zone_new_local().
*
* @newin{2,26}
*
* @return The newly created DateTime.
*/
DateTime to_local() const;
/** Creates a new DateTime corresponding to the same instant in time as
* @a datetime, but in UTC.
*
* This call is equivalent to calling g_date_time_to_timezone() with the
* time zone returned by g_time_zone_new_utc().
*
* @newin{2,26}
*
* @return The newly created DateTime.
*/
DateTime to_utc() const;
/** Creates a newly allocated string representing the requested @a format.
*
* The format strings understood by this function are a subset of the
* strftime() format language as specified by C99. The \\%D, \\%U and \\%W
* conversions are not supported, nor is the 'E' modifier. The GNU
* extensions \\%k, \\%l, \\%s and \\%P are supported, however, as are the
* '0', '_' and '-' modifiers.
*
* In contrast to strftime(), this function always produces a UTF-8
* string, regardless of the current locale. Note that the rendering of
* many formats is locale-dependent and may not match the strftime()
* output exactly.
*
* The following format specifiers are supported:
*
* - \\%a: the abbreviated weekday name according to the current locale
* - \\%A: the full weekday name according to the current locale
* - \\%b: the abbreviated month name according to the current locale
* - \\%B: the full month name according to the current locale
* - \\%c: the preferred date and time rpresentation for the current locale
* - \\%C: the century number (year/100) as a 2-digit integer (00-99)
* - \\%d: the day of the month as a decimal number (range 01 to 31)
* - \\%e: the day of the month as a decimal number (range 1 to 31)
* - \\%F: equivalent to `%Y-%m-%d` (the ISO 8601 date format)
* - \\%g: the last two digits of the ISO 8601 week-based year as a
* decimal number (00-99). This works well with \\%V and \\%u.
* - \\%G: the ISO 8601 week-based year as a decimal number. This works
* well with \\%V and \\%u.
* - \\%h: equivalent to \\%b
* - \\%H: the hour as a decimal number using a 24-hour clock (range 00 to 23)
* - \\%I: the hour as a decimal number using a 12-hour clock (range 01 to 12)
* - \\%j: the day of the year as a decimal number (range 001 to 366)
* - \\%k: the hour (24-hour clock) as a decimal number (range 0 to 23);
* single digits are preceded by a blank
* - \\%l: the hour (12-hour clock) as a decimal number (range 1 to 12);
* single digits are preceded by a blank
* - \\%m: the month as a decimal number (range 01 to 12)
* - \\%M: the minute as a decimal number (range 00 to 59)
* - \\%p: either "AM" or "PM" according to the given time value, or the
* corresponding strings for the current locale. Noon is treated as
* "PM" and midnight as "AM".
* - \\%P: like \\%p but lowercase: "am" or "pm" or a corresponding string for
* the current locale
* - \\%r: the time in a.m. or p.m. notation
* - \\%R: the time in 24-hour notation (\\%H:\\%M)
* - \\%s: the number of seconds since the Epoch, that is, since 1970-01-01
* 00:00:00 UTC
* - \\%S: the second as a decimal number (range 00 to 60)
* - \\%t: a tab character
* - \\%T: the time in 24-hour notation with seconds (\\%H:\\%M:\\%S)
* - \\%u: the ISO 8601 standard day of the week as a decimal, range 1 to 7,
* Monday being 1. This works well with \\%G and \\%V.
* - \\%V: the ISO 8601 standard week number of the current year as a decimal
* number, range 01 to 53, where week 1 is the first week that has at
* least 4 days in the new year. See g_date_time_get_week_of_year().
* This works well with \\%G and \\%u.
* - \\%w: the day of the week as a decimal, range 0 to 6, Sunday being 0.
* This is not the ISO 8601 standard format -- use \\%u instead.
* - \\%x: the preferred date representation for the current locale without
* the time
* - \\%X: the preferred time representation for the current locale without
* the date
* - \\%y: the year as a decimal number without the century
* - \\%Y: the year as a decimal number including the century
* - \\%z: the time zone as an offset from UTC (+hhmm)
* - \\%:z: the time zone as an offset from UTC (+hh:mm).
* This is a gnulib strftime() extension. @newin{2,38}
* - \\%::z: the time zone as an offset from UTC (+hh:mm:ss). This is a
* gnulib strftime() extension. @newin{2,38}
* - \\%:::z: the time zone as an offset from UTC, with : to necessary
* precision (e.g., -04, +05:30). This is a gnulib strftime() extension. @newin{2,38}
* - \\%Z: the time zone or name or abbreviation
* - \\%\\%: a literal \\% character
*
* Some conversion specifications can be modified by preceding the
* conversion specifier by one or more modifier characters. The
* following modifiers are supported for many of the numeric
* conversions:
*
* - O: Use alternative numeric symbols, if the current locale supports those.
* - _: Pad a numeric result with spaces. This overrides the default padding
* for the specifier.
* - -: Do not pad a numeric result. This overrides the default padding
* for the specifier.
* - 0: Pad a numeric result with zeros. This overrides the default padding
* for the specifier.
*
* @newin{2,26}
*
* @param format A valid UTF-8 string, containing the format for the
* DateTime.
* @return A newly allocated string formatted to the requested format
* or <tt>0</tt> in the case that there was an error. The string
* should be freed with g_free().
*/
Glib::ustring format(const Glib::ustring& format) const;
};
} // namespace Glib
namespace Glib
{
/** A Glib::wrap() method for this object.
*
* @param object The C instance.
* @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
* @result A C++ instance that wraps this C instance.
*
* @relates Glib::DateTime
*/
Glib::DateTime wrap(GDateTime* object, bool take_copy = false);
} // namespace Glib
#endif /* _GLIBMM_DATETIME_H */
|