You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: packages/codecs-core/README.md
+19-19Lines changed: 19 additions & 19 deletions
Original file line number
Diff line number
Diff line change
@@ -38,10 +38,10 @@ const person = personCodec.decode(bytes);
38
38
39
39
There is a significant library of composable codecs at your disposal, enabling you to compose complex types. You may be interested in the documentation of these other packages to learn more about them:
40
40
41
-
-[`@solana/codecs-numbers`](https://github.com/anza-xyz/solana-web3.js/tree/main/packages/codecs-numbers) for number codecs.
42
-
-[`@solana/codecs-strings`](https://github.com/anza-xyz/solana-web3.js/tree/main/packages/codecs-strings) for string codecs.
43
-
-[`@solana/codecs-data-structures`](https://github.com/anza-xyz/solana-web3.js/tree/main/packages/codecs-data-structures) for many data structure codecs such as objects, arrays, tuples, sets, maps, enums, discriminated unions, booleans, etc.
44
-
-[`@solana/options`](https://github.com/anza-xyz/solana-web3.js/tree/main/packages/options) for a Rust-like `Option` type and associated codec.
41
+
-[`@solana/codecs-numbers`](https://github.com/anza-xyz/solana-web3.js/tree/main/packages/codecs-numbers) for number codecs.
42
+
-[`@solana/codecs-strings`](https://github.com/anza-xyz/solana-web3.js/tree/main/packages/codecs-strings) for string codecs.
43
+
-[`@solana/codecs-data-structures`](https://github.com/anza-xyz/solana-web3.js/tree/main/packages/codecs-data-structures) for many data structure codecs such as objects, arrays, tuples, sets, maps, enums, discriminated unions, booleans, etc.
44
+
-[`@solana/options`](https://github.com/anza-xyz/solana-web3.js/tree/main/packages/options) for a Rust-like `Option` type and associated codec.
45
45
46
46
You may also be interested in some of the helpers of this `@solana/codecs-core` library such as `transformCodec`, `fixCodecSize` or `reverseCodec` that create new codecs from existing ones.
47
47
@@ -159,19 +159,19 @@ The following type guards are available to identify and/or assert the size of co
159
159
160
160
Finally, note that the same is true for `Encoders` and `Decoders`.
161
161
162
-
-A `FixedSizeEncoder` has a `fixedSize` number attribute.
163
-
-A `VariableSizeEncoder` has a `getSizeFromValue` function and an optional `maxSize` number attribute.
164
-
-A `FixedSizeDecoder` has a `fixedSize` number attribute.
165
-
-A `VariableSizeDecoder` has an optional `maxSize` number attribute.
162
+
- A `FixedSizeEncoder` has a `fixedSize` number attribute.
163
+
- A `VariableSizeEncoder` has a `getSizeFromValue` function and an optional `maxSize` number attribute.
164
+
- A `FixedSizeDecoder` has a `fixedSize` number attribute.
165
+
- A `VariableSizeDecoder` has an optional `maxSize` number attribute.
166
166
167
167
## Creating custom codecs
168
168
169
169
If composing codecs isn’t enough for you, you may implement your own codec logic by using the `createCodec` function. This function requires an object with a `read` and a `write` function telling us how to read from and write to an existing byte array.
170
170
171
171
The `read` function accepts the `bytes` to decode from and the `offset` at each we should start reading. It returns an array with two items:
172
172
173
-
-The first item should be the decoded value.
174
-
-The second item should be the next offset to read from.
173
+
- The first item should be the decoded value.
174
+
- The second item should be the next offset to read from.
Both the `preOffset` and `postOffset` functions offer the following attributes:
535
535
536
-
-`bytes`: The entire byte array being encoded or decoded.
537
-
-`preOffset`: The original and unaltered pre-offset.
538
-
-`wrapBytes`: A helper function that wraps the given offset around the byte array length. E.g. `wrapBytes(-1)` will refer to the last byte of the byte array.
536
+
-`bytes`: The entire byte array being encoded or decoded.
537
+
-`preOffset`: The original and unaltered pre-offset.
538
+
-`wrapBytes`: A helper function that wraps the given offset around the byte array length. E.g. `wrapBytes(-1)` will refer to the last byte of the byte array.
539
539
540
540
Additionally, the post-offset function also provides the following attributes:
541
541
542
-
-`newPreOffset`: The new pre-offset after the pre-offset function has been applied.
543
-
-`postOffset`: The original and unaltered post-offset.
542
+
-`newPreOffset`: The new pre-offset after the pre-offset function has been applied.
543
+
-`postOffset`: The original and unaltered post-offset.
544
544
545
545
Note that you may also decide to ignore these attributes to achieve absolute offsets. However, relative offsets are usually recommended as they won't break your codecs when composed with other codecs.
However, you may use the `size` option to configure this behaviour. It can be one of the following three strategies:
37
37
38
-
-`Codec<number>`: When a number codec is provided, that codec will be used to encode and decode the size prefix.
39
-
-`number`: When a number is provided, the codec will expect a fixed number of items in the array. An error will be thrown when trying to encode an array of a different length.
40
-
-`"remainder"`: When the string `"remainder"` is passed as a size, the codec will use the remainder of the bytes to encode/decode its items. This means the size is not stored or known in advance but simply inferred from the rest of the buffer. For instance, if we have an array of `u16` numbers and 10 bytes remaining, we know there are 5 items in this array.
38
+
-`Codec<number>`: When a number codec is provided, that codec will be used to encode and decode the size prefix.
39
+
-`number`: When a number is provided, the codec will expect a fixed number of items in the array. An error will be thrown when trying to encode an array of a different length.
40
+
-`"remainder"`: When the string `"remainder"` is passed as a size, the codec will use the remainder of the bytes to encode/decode its items. This means the size is not stored or known in advance but simply inferred from the rest of the buffer. For instance, if we have an array of `u16` numbers and 10 bytes remaining, we know there are 5 items in this array.
In Rust, enums are powerful data types whose variants can be one of the following:
312
312
313
-
-An empty variant — e.g. `enum Message { Quit }`.
314
-
-A tuple variant — e.g. `enum Message { Write(String) }`.
315
-
-A struct variant — e.g. `enum Message { Move { x: i32, y: i32 } }`.
313
+
- An empty variant — e.g. `enum Message { Quit }`.
314
+
- A tuple variant — e.g. `enum Message { Write(String) }`.
315
+
- A struct variant — e.g. `enum Message { Move { x: i32, y: i32 } }`.
316
316
317
317
Whilst we do not have such powerful enums in JavaScript, we can emulate them in TypeScript using a union of objects such that each object is differentiated by a specific field. **We call this a discriminated union**.
318
318
@@ -434,9 +434,9 @@ The `getUnionCodec` is a lower-lever codec helper that can be used to encode/dec
434
434
435
435
It accepts the following arguments:
436
436
437
-
-An array of codecs, each defining a variant of the union.
438
-
-A `getIndexFromValue` function which, given a value of the union, returns the index of the codec that should be used to encode that value.
439
-
-A `getIndexFromBytes` function which, given the byte array to decode at a given offset, returns the index of the codec that should be used to decode the next bytes.
437
+
- An array of codecs, each defining a variant of the union.
438
+
- A `getIndexFromValue` function which, given a value of the union, returns the index of the codec that should be used to encode that value.
439
+
- A `getIndexFromBytes` function which, given the byte array to decode at a given offset, returns the index of the codec that should be used to decode the next bytes.
0 commit comments