add note about on 32 vs 64 bit systems

hamba · Jul 29, 2024 · 1455995 · 1455995
1 parent 79482f8
commit 1455995
Showing 1 changed file with 34 additions and 29 deletions.
diff --git a/README.md b/README.md
@@ -68,35 +68,40 @@ More examples in the [godoc](https://pkg.go.dev/github.com/hamba/avro/v2).
 
 #### Types Conversions
 
-| Avro                          | Go Struct                                              | Go Interface             |
-|-------------------------------|--------------------------------------------------------|--------------------------|
-| `null`                        | `nil`                                                  | `nil`                    |
-| `boolean`                     | `bool`                                                 | `bool`                   |
-| `bytes`                       | `[]byte`                                               | `[]byte`                 |
-| `float`                       | `float32`                                              | `float32`                |
-| `double`                      | `float64`                                              | `float64`                |
-| `long`                        | `int64`, `uint32`\*                                    | `int64`, `uint32`        |
-| `int`                         | `int`, `int32`, `int16`, `int8`, `uint8`\*, `uint16`\* | `int`, `uint8`, `uint16` |
-| `fixed`                       | `uint64`                                               | `uint64`                 |
-| `string`                      | `string`                                               | `string`                 |
-| `array`                       | `[]T`                                                  | `[]any`                  |
-| `enum`                        | `string`                                               | `string`                 |
-| `fixed`                       | `[n]byte`                                              | `[n]byte`                |
-| `map`                         | `map[string]T{}`                                       | `map[string]any`         |
-| `record`                      | `struct`                                               | `map[string]any`         |
-| `union`                       | *see below*                                            | *see below*              |
-| `int.date`                    | `time.Time`                                            | `time.Time`              |
-| `int.time-millis`             | `time.Duration`                                        | `time.Duration`          |
-| `long.time-micros`            | `time.Duration`                                        | `time.Duration`          |
-| `long.timestamp-millis`       | `time.Time`                                            | `time.Time`              |
-| `long.timestamp-micros`       | `time.Time`                                            | `time.Time`              |
-| `long.local-timestamp-millis` | `time.Time`                                            | `time.Time`              |
-| `long.local-timestamp-micros` | `time.Time`                                            | `time.Time`              |
-| `bytes.decimal`               | `*big.Rat`                                             | `*big.Rat`               |
-| `fixed.decimal`               | `*big.Rat`                                             | `*big.Rat`               |
-| `string.uuid`                 | `string`                                               | `string`                 |
-
-\* Please note that when the Go type is an unsigned integer care must be taken to ensure that information is not lost 
+| Avro                          | Go Struct                                                  | Go Interface             |
+|-------------------------------|------------------------------------------------------------|--------------------------|
+| `null`                        | `nil`                                                      | `nil`                    |
+| `boolean`                     | `bool`                                                     | `bool`                   |
+| `bytes`                       | `[]byte`                                                   | `[]byte`                 |
+| `float`                       | `float32`                                                  | `float32`                |
+| `double`                      | `float64`                                                  | `float64`                |
+| `long`                        | `int`\*, `int64`, `uint32`\**                              | `int`, `int64`, `uint32` |
+| `int`                         | `int`\*, `int32`, `int16`, `int8`, `uint8`\**, `uint16`\** | `int`, `uint8`, `uint16` |
+| `fixed`                       | `uint64`                                                   | `uint64`                 |
+| `string`                      | `string`                                                   | `string`                 |
+| `array`                       | `[]T`                                                      | `[]any`                  |
+| `enum`                        | `string`                                                   | `string`                 |
+| `fixed`                       | `[n]byte`                                                  | `[n]byte`                |
+| `map`                         | `map[string]T{}`                                           | `map[string]any`         |
+| `record`                      | `struct`                                                   | `map[string]any`         |
+| `union`                       | *see below*                                                | *see below*              |
+| `int.date`                    | `time.Time`                                                | `time.Time`              |
+| `int.time-millis`             | `time.Duration`                                            | `time.Duration`          |
+| `long.time-micros`            | `time.Duration`                                            | `time.Duration`          |
+| `long.timestamp-millis`       | `time.Time`                                                | `time.Time`              |
+| `long.timestamp-micros`       | `time.Time`                                                | `time.Time`              |
+| `long.local-timestamp-millis` | `time.Time`                                                | `time.Time`              |
+| `long.local-timestamp-micros` | `time.Time`                                                | `time.Time`              |
+| `bytes.decimal`               | `*big.Rat`                                                 | `*big.Rat`               |
+| `fixed.decimal`               | `*big.Rat`                                                 | `*big.Rat`               |
+| `string.uuid`                 | `string`                                                   | `string`                 |
+
+\* Please note that the size of the Go type `int` is platform dependent. Decoding an Avro `long` into a Go `int` is
+only allowed on 64-bit platforms and will result in an error on 32-bit platforms. Similarly, be careful when encoding a
+Go `int` using Avro `int` on a 64-bit platform, as that can result in an integer overflow causing misinterpretation of
+the data.
+
+\** Please note that when the Go type is an unsigned integer care must be taken to ensure that information is not lost
 when converting between the Avro type and Go type. For example, storing a *negative* number in Avro of `int = -100`
 would be interpreted as `uint16 = 65,436` in Go. Another example would be storing numbers in Avro `int = 256` that 
 are larger than the Go type `uint8 = 0`.