~henryprecheur/cbor commit

1 files changed, 50 insertions(+), 50 deletions(-)

M episode11/README.md

M episode11/README.md +50 -50

@@ 38,11 38,11 @@ one:
 
 ----
 
-In the [previous episode][ep10] we added better floating point number support to
-our encoder. We implemented all the Go native types, now we’ll implement a
-custom stype: time.Time, a timestamp type from Go’s standard library. The CBOR
-format [supports](https://tools.ietf.org/html/rfc7049#section-2.4.1) 3 timestamp
-types natively:
+In the [previous episode][ep10] we improved floating point number support in our
+encoder. We implemented all the Go native types, now we’ll implement a custom
+stype: time.Time, a timestamp type from Go’s standard library. The CBOR format
+[supports](https://tools.ietf.org/html/rfc7049#section-2.4.1) 3 timestamp types
+natively:
 
 - RFC3339 string like "2019-02-01T17:45:23Z"
 - floating point epoch based values

          
@@ 55,19 55,18 @@ tagged type has a unique integer identif
 
 For example URIs are represented as a tagged unicode string: first there’s the
 header with the major type 6 —indicating it’s a tagged value— encoding the
-integer 32 —the identifies that corresponds to URIs—, the header is followed by
-the URI encoded as an UTF-8 CBOR string.
+integer 32 —the URIs’ identifier—, followed by the URI encoded as an UTF-8 CBOR
+string.
 
-How can we detect if we have a time.Time value in the encoder?
-Looking at [time.Time’s definition](https://godoc.org/time#Time) we see that
-it’s a struct, a kind of value we already handle in the encoder. The reflect
-package lets us query and compare value types, so we will check if the value’s
-type is time.Time when we have a reflect.Struct kind and write a CBOR timestamp
-when that’s the case.
+How can we detect if we have a time.Time value in the encoder? Looking at
+[time.Time’s definition](https://godoc.org/time#Time) we see that it’s a struct,
+a kind of value we already handle in the encoder. The reflect package lets us
+query and compare value’s types, so we will check if the value’s type is
+time.Time when we have a reflect.Struct kind and write a CBOR timestamp when
+that’s the case.
 
-In the main switch block we add a conditional statement in the reflect.Struct
-case to handle time.Time if it’s the value’s type. There’s a bit of gymnastic
-needed to get time.Time’s type without allocating extra stuff, we can either do:
+There’s a bit of gymnastic needed to get time.Time’s type without allocating
+extra stuff, we can either do:
 
     reflect.TypeOf(time.Time{})
 

          
@@ 76,10 75,13 @@ Or:
     reflect.TypeOf((*time.Time)(nil)).Elem()
 
 In the first case we create an empty time.Time object, pass an interface
-pointing to it to reflect.TypeOf to retreive the reflect.Type we are after.
-In the second case we create an empty interface to time.Time and retreive its
-type directly. We’ll use the second way because it doesn’t create an empty
-time.Time object and is therefor a bit more efficient:
+pointing to it to reflect.TypeOf that will return its reflect.Type. In the
+second case we create an empty interface to time.Time and retreive its type
+directly. We’ll use the second way because it doesn’t create an empty time.Time
+object and is therefor a bit more efficient.
+
+In the main switch block we add a conditional statement in the reflect.Struct
+case to check is the struct’s type is time.Time:
 
 	case reflect.Struct:
 		if x.Type() == reflect.TypeOf((*time.Time)(nil)).Elem() {

          
@@ 88,11 90,11 @@ time.Time object and is therefor a bit m
 		return e.writeStruct(x)
 
 Timestamps have two tagged data item types: 0 for RFC3339 timestamps encoded as
-unicode strings, or 1 for epoch-based timestamps —this include floating point &
-integer values—. Let’s add a new function to write the timestamps: writeTime.
-First we’ll handle string timestamps, and implement scalar epoch-based timestamp
-types second. Starting with [RFC3339][rfc3339] strings, we lookup the example
-from the spec, and add our first test case:
+unicode strings, or 1 for epoch-based timestamps —floating point & integer
+values—. Let’s add a new function to write the timestamps: writeTime. We’ll
+handle string timestamps first, and implement scalar epoch-based timestamp types
+second. Starting with [RFC3339][rfc3339] strings, we lookup the example from the
+spec, and add our first test case:
 
     func TestTimestamp(t *testing.T) {
         var rfc3339Timestamp, _ = time.Parse(time.RFC3339, "2013-03-21T20:04:00Z")

          
@@ 154,22 156,21 @@ switch statement:
 		}
 		return e.writeStruct(x)
 
-A quick `go test` to confirm writing string timestamps works.
-
-We are done with string timestamps, epoch-based timestamps are next. Epoch-based
-timestamps are scalar values where 0 corresponds to the Unix epoch (January 1,
-1970), that can either be integer or floating point values.
+A quick `go test` to confirm writing string timestamps works, so let’s get
+started with epoch-based timestamps.
 
-We’ll minimize the size of our output by using the most compact type we can use
-without losing precision. The timestamp can either be an integer, a floating
-point number, or a RFC3339 string. If the timestamp’s timezone isn’t UTC we’ll
-have to use the largest type: RFC3339 strings, because we need to encode the
-timezone information and we can’t do it with scalar timestamps. If the
-timestamp’s timezone is UTC or is nil we can use a scalar timestamp because they
-use UTC time. We’ll use an integer when the timestamp can be represented as
-whole seconds and use floating point number otherwise.
+Epoch-based timestamps are scalar values where 0 corresponds to the Unix epoch
+(January 1, 1970), that can either be integer or floating point values. We’ll
+minimize the size of our output by using the most compact type without losing
+precision. The timestamp can either be an integer, a floating point number, or a
+RFC3339 string. If the timestamp’s timezone isn’t UTC we’ll have to use the
+largest type: RFC3339 strings, because we need to encode the timezone
+information and we can’t do it with scalar timestamps. If the timestamp’s
+timezone is UTC or is nil we can use a scalar timestamp because they are set in
+UTC time. We’ll use an integer when the timestamp can be represented as whole
+seconds or use a floating point number otherwise.
 
-First we’ll add a condition to only use RFC3339 strings when the timestamp has a
+First we add a condition to only use RFC3339 strings when the timestamp has a
 timezone that’s not UTC:
 
     func (e *Encoder) writeTime(v reflect.Value) error {

          
@@ 225,19 226,18 @@ encode. As usual we start by adding a te
         ...
     }
 
-Note that we had to call the .UTC() method on the time.Time object return by
-time.Unix, that’s because otherwise the object will have the local timezone
-associated with it. So we call the UTC method to get the timestamp set at UTC
-timezone.
+Note that we had to call the .UTC() method on the time.Time object returned by
+time.Unix, that’s because otherwise the object will have the computer’s local
+timezone associated to it, a call on the UTC method get us a UTC timestamp.
 
-Because time.Time store its internal time as an integer counting the
-number of nanoseconds since the Epoch, we’ll have to convert it into a floating
-point number in seconds before writing it. To do this we define a constant to
-convert from nanoseconds to seconds from the time’s module units:
+Since time.Time stores its internal time as an integer counting the number of
+nanoseconds since the Epoch, we’ll have to convert it into a floating point
+number in seconds before writing it. To do this we define a constant to convert
+from nanoseconds to seconds from the time’s module units:
 
     const nanoSecondsInSecond = time.Second / time.Nanosecond
 
-We add our new code after the block to handle string timestamps. We write the
+Then we add the code after the block to handle string timestamps. We write the
 header with minorTimeEpoch as its sub-type to indicate we have a scalar
 timestamp, then write the converted value as a floating point number:
 

          
@@ 261,8 261,8 @@ timestamp, then write the converted valu
 
 If the timestamp in seconds is an integer number we can write it as an integer
 timestamp without losing precision. Integers are usually more compact than
-floating point numbers, so we’ll always use them when possible. Another test
-case from the spec makes it into cbor_test.go:
+floating point numbers, we’ll always use them when possible. Another test case
+from the spec makes it into cbor_test.go:
 
     func TestTimestamp(t *testing.T) {
         ...