Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

glib: Add GDateTime, GTimeSpan, and GTimer.

  • Loading branch information...
commit a10656298748e91b9d29c291bfe01586a0c3a429 1 parent 224cc28
Christian Hergert authored November 13, 2012

Showing 1 changed file with 97 additions and 0 deletions. Show diff stats Hide diff stats

  1. 97  tex/glib_datetime.tex
97  tex/glib_datetime.tex
@@ -56,11 +56,108 @@ \section{GTimeVal}
56 56
 
57 57
 \section{GDateTime}
58 58
 
  59
+\verb|GDateTime| is a structure that tracks the combination of a date, time of day, and timezone for you.
  60
+One purpose of this structure is to simplify manipulation of dates and times.
  61
+For example, with \verb|GTimeVal| you would need to convert to another structure such as \verb|struct tm| to manipulate days, weeks, or months accurately.
  62
+With \verb|GDateTime| that is all handled for you.
  63
+
  64
+\verb|GDateTime| is \emph{referenced counted}.
  65
+That means that you are responsible for releasing the memory back to the system when you are done with it using \verb|g_date_time_unref()|.
  66
+
  67
+Additionally, \verb|GDateTime| is \emph{immutable}.
  68
+That means that every time you make a change, you receive a new instance of a \verb|GDateTime|.
  69
+Don't forget to unref them!
  70
+
  71
+\begin{code}{}
  72
+GDateTime *now;
  73
+GDateTime *then;
  74
+gchar *str;
  75
+
  76
+now = g_date_time_new_local();
  77
+then = g_date_time_add_weeks(now, 3);
  78
+str = g_date_time_printf(then, "%x %X");
  79
+
  80
+g_print("In three weeks, it will be %s\n", str);
  81
+
  82
+g_free(str);
  83
+g_date_time_unref(then);
  84
+g_date_time_unref(now);
  85
+\end{code}
  86
+
  87
+You can event use \verb|GDateTime| as the key in a \verb|GHashTable|.
  88
+Simply use the provided \verb|GHashFunc| and \verb|GEqualFunc| for \verb|GDateTime|.
  89
+
  90
+\begin{code}{}
  91
+GHashTable *ht;
  92
+GDateTime *dt;
  93
+gchar *str;
  94
+
  95
+ht = g_hash_table_new_full(g_date_time_hash,
  96
+                           g_date_time_equal,
  97
+                           g_date_time_unref,
  98
+                           g_free);
  99
+dt = g_date_time_new_now_local();
  100
+str = g_date_time_format(dt, "%x %X");
  101
+g_hash_table_insert(ht, dt, str);
  102
+\end{code}
  103
+
  104
+
  105
+\section{GTimeSpan}
  106
+
  107
+\verb|GDateTime| introduces the concept of a time-span as \verb|GTimeSpan|.
  108
+This is the number of microseconds between to dates and times.
  109
+This is not meant for profiling how long code takes to run.
  110
+You would want \verb|GTimer| for that.
  111
+However, it is appropriate for determining the amount of time between two chat messages.
  112
+
  113
+\verb|GTimeSpan| is a \verb|gint64|.
  114
+Therefore there is no need to free any memory when differencing two \verb|GDateTime|s.
  115
+The following example calculates the number of days since January 1, 2000.
  116
+
  117
+\begin{code}{}
  118
+GDateTime *now;
  119
+GDateTime *jan12000;
  120
+GTimeSpan diff;
  121
+
  122
+now = g_date_time_new_now_utc();
  123
+jan12000 = g_date_time_new_utc(2000, 1, 1, 0, 0, 0);
  124
+diff = g_date_time_difference(jan12000, now);
  125
+
  126
+g_print("%"G_GINT64_FORMAT" days since Jan 1, 2000.\n",
  127
+        jan12000 / G_TIME_SPAN_DAY);
  128
+
  129
+g_date_time_unref(now);
  130
+g_date_time_unref(jan12000);
  131
+\end{code}
59 132
 
60 133
 
61 134
 \section{GTimeZone}
62 135
 
63 136
 
  137
+\section{GTimer}
  138
+
  139
+\verb|GTimer| is a structure used for calculating how much wall clock time has elapsed.
  140
+It is typically used to profile how long something takes to run.
  141
+For example, if you want to now if a particular optimization is faster, \verb|GTimer| is a very simple way to achieve that.
  142
+
  143
+There is no need to start a timer, it is started as soon as you create it.
  144
+Simply stop it when you are finished.
  145
+If you want to re-use a timer, you can call \verb|g_timer_reset()| to restart it.
  146
+
  147
+\begin{code}{}
  148
+GTimer *timer;
  149
+gdouble elapsed;
  150
+
  151
+timer = g_timer_new();
  152
+test_1();
  153
+g_timer_stop(timer);
  154
+elapsed = g_timer_elapsed(timer, NULL);
  155
+g_print("%lf seconds elapsed.\n", elapsed);
  156
+g_timer_destroy(timer);
  157
+
  158
+\end{code}
  159
+
  160
+
64 161
 \section{Miscellaneous}
65 162
 
66 163
 TODO

0 notes on commit a106562

Please sign in to comment.
Something went wrong with that request. Please try again.