Types¶
This section documents all the valid data types that are accepted by various shards either as their input value or as a parameter value. These data types also apply to the output created by any shard.
Valid data types for every shard are listed under the Type column of their Parameters, Input, and Output sections (types are enclosed within parentheses and if multiple types apply then they are separated by a space).
Compound types
While this section lists the simple (or primitive) data types, you can combine these to create compound data types. For example, combining Int, String, and Seq, can give you a sequence of sequences [ [ Any ] ], a sequence of integers and strings [ Int String ]), and so on.
Why types?
Types are helpful as they reduce errors in programming. They are also very useful in visual programming as type-matching can be used to reduce the dropdown options when prompting a user on what shard to use next (depending on which shard's input type matches with the current shard's output type).
Note
While all the following types are available internally to various shards, only a few are currently accessible in the Shards scripting environment. Consequently, only these types have keywords/aliases.
Any¶
Type Any indicates that all data types are allowed.
For example, Any as the allowed data type for input and :Value parameter of shard (All) means that (All) accepts and compares across all data types.
1 2 | |
(All) compares the input and:Value parameter values and returns true only if both the value and data type of these entities is equal/same.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | |
[info] [2022-07-22 13:05:25.848] [T-18072] [logging.cpp::55] [mywire] true
[info] [2022-07-22 13:05:25.861] [T-18072] [logging.cpp::55] [mywire] true
[info] [2022-07-22 13:05:25.862] [T-18072] [logging.cpp::55] [mywire] false
[info] [2022-07-22 13:05:25.864] [T-18072] [logging.cpp::55] [mywire] false
Sequence¶
Type Sequence is a collection of values that can be accessed directly via indexes (since items are indexed by contiguous integers).
It is also called a vector or an array. A Sequence's items are accessible by index. Example of a Sequence type would be: [43 6 1].
Audio¶
Type Audio is uncompressed audio data.
Examples of shards that use this type are (Audio.Oscillator), (Audio.ReadFile), and (Audio.WriteFile) all of which generate Audio type data as their output.
Supported formats
Shards supports the audio formats WAV, MP3, OGG, and FLAC.
Bool¶
Type Bool allows only two values - true or false.
In that sense, it can be thought of as a special case of an Enum data type.
Consider the shard (Is). This shard compares its input and the value in the :Value parameter for equality and returns true if values are equal, otherwise false if values are not equal. Examples:
1 2 3 4 5 | |
[info] [2022-07-22 18:38:24.383] [T-25360] [logging.cpp::55] [mywire] true
[info] [2022-07-22 18:38:24.395] [T-25360] [logging.cpp::55] [mywire] false
Bytes¶
Type Bytes represents binary data.
Note
Has keyword bytes and alias Bytes.
A byte is made up of 8 bits (for example, 10111010) and a Bytes type is an sequence of such bytes: [11110001 10110111 10000111]
Bits and Bytes
Bits are how data is stored in a computer at the level of electrical circuits. A bit can have only two values (1 or 0, representing the circuit is on or off) - hence the name binary data. A group of eight bits make a byte: 11111111, 10101010, etc. Since a bit can have only two values, a Byte can represent a total of 256 numbers (2^8): 0 to 255.
Shards like (ToBytes), (BytesToString), (BytesToInts), etc, all use the type Bytes either for their input or their output.
Color¶
Type Color represents an RGBA color format and is constructed from four unsigned 8 bit integers (one each for the R, G, B, and A values).
Note
Has keyword color and alias Color.
Each of the R, G, B, and A values range from 0 to 255. R, G, and B stand for red, blue, and green components of the color. A represents the alpha channel property (how opaqe a pixel is - 0 is fully transparent, 255 is fully opaque).
The shard (ToColor) converts its input into a Color type.
1 2 3 4 5 6 7 8 | |
[info] [2022-07-26 19:08:24.520] [T-24408] [logging.cpp::55] [mywire] 255, 10, 10, 1
[info] [2022-07-26 19:08:24.533] [T-24408] [logging.cpp::55] [mywire] 23, 45, 56, 78
[info] [2022-07-26 19:08:24.534] [T-24408] [logging.cpp::55] [mywire] 0, 0, 0, 0
ContextVar¶
Type ContextVar represents a contextual variable (i.e., a variable that is in scope for the shard processing this data).
Note
Has keyword context-var and alias ContextVar.
The shard (Math.Inc) accepts only ContextVar type numeric data (i.e., a variable that holds numeric data) into its :Value parameter, and increments it by 1.
1 2 3 4 5 6 7 | |
[info] [2022-07-26 19:30:22.837] [T-27800] [logging.cpp::55] [mywire] 12
[info] [2022-07-26 19:30:22.843] [T-27800] [logging.cpp::55] [mywire] (5.5, 6.7)
Enum¶
Enum stands for enumerated data type.
Note
Has keyword enum and alias Enum.
The value that you pass to an enumerated variable can only take certain 'states' or named constant values.
For an overview of all enums and valid values check the Enums page
For example, in (Math.Mean) the value for :Kind parameter needs to be of type Mean.
1 | |
(Math.Mean) computes the mean of a sequence of floating-point numbers. But there are three kinds of means - Arithmetic mean, Geometric mean, and Harmonic mean.
So the parameter :Kind is defined as an enum variable with these three fixed states :
:Kind = {Arithmtic mean, Geometric mean, Harmonic mean}
And hence :Kind expects a value that matches one of its possible states. In other words the value you pass in for :Kind needs to be an enumerated data type.
In simple terms it just means that you pass in one of the allowed named constant values. Anything else will fail validation.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | |
[info] [2022-07-22 15:35:00.868] [T-15316] [logging.cpp::55] [mywire] 6
[info] [2022-07-22 15:35:00.881] [T-15316] [logging.cpp::55] [mywire] 4.47214
[info] [2022-07-22 15:35:00.882] [T-15316] [logging.cpp::55] [mywire] 3.33333
[info] [2022-07-22 15:35:00.883] [T-15316] [logging.cpp::55] [mywire] 6
Float¶
Type Float defines a 64-bit signed floating point number.
Note
Has keyword float and alias Float.
Floating point means it has the capability to store a decimal point and hence supports decimal numbers.
64 bits of memory allows this data type to support a very large range of positive and negative decimal numbers (16 significant decimal digits and an exponent range of −383 to +384).
A Float value looks like this: (float 2.53).
It may also be represented without the keyword float, with just the floating-point value: 2.53.
(Math.Add) is an example of a shard that uses this data type for its input, output, and :Operand parameter.
1 2 3 4 5 | |
[info] [2022-07-22 22:06:32.856] [T-20204] [logging.cpp::55] [mywire] 3.83
[info] [2022-07-22 22:06:32.873] [T-20204] [logging.cpp::55] [mywire] 3.83
Float2¶
Type Float2 defines a vector of two Float type numbers.
Note
Has keyword float2 and alias Float2.
A vector can be thought of as a group or list of items that are considered together for processing.
A Float2 type value looks like this: (float2 3.4 -5.0).
(Math.Add) is an example of a shard that uses this data type for its input, output, and :Operand parameter.
1 2 | |
[info] [2022-07-22 22:10:00.688] [T-24616] [logging.cpp::55] [mywire] (10.4, 14.2)
Float3¶
Type Float3 defines a vector of three 32-bit signed floating point numbers.
Note
Has keyword float3 and alias Float3.
Floating point means it has the capability to store a decimal point and hence supports decimal numbers.
32 bits of memory allows this data type to support a large range of positive and negative decimal numbers (7 significant decimal digits and an exponent range of −101 to +90).
A Float3 type value looks like this: (float3 2.9 -4.23 7.83).
(Math.Add) is an example of a shard that uses this data type for its input, output, and :Operand parameter.
1 2 | |
[info] [2022-07-22 22:19:36.923] [T-16128] [logging.cpp::55] [mywire] (7.7, 7.7, 7.7)
Float4¶
Type Float4 is like type Float3 but is a vector of four 32-bit signed floating point numbers instead.
Note
Has keyword float4 and alias Float4.
A Float4 type value looks like this: (float4 -8.84 38.2 4.7 0.4).
(Math.Add) is an example of a shard that uses this data type for its input, output, and :Operand parameter.
1 2 3 | |
[info] [2022-07-22 22:23:24.076] [T-25152] [logging.cpp::55] [mywire] (9.9, 9.9, 10.1, 9.9)
Image¶
Type Image is uncompressed image data.
A shard that uses this type is (StripAlpha). This takes an Image type input, strips out its alpha (transparency) channel, and outputs an Image type (transformed image).
Supported formats
Shards supports the image formats PNG and SVG.
Int¶
Type Int defines a 64-bit signed integer.
Note
Has keyword int and alias Int.
64 bits of memory allows this data type to store integer values ranging from -9,223,372,036,854,775,808 to +9,223,372,036,854,775,807 (no decimals).
An Int value looks like this: (int 2).
It may also be represented without the keyword int, with just the integer value: 2.
(Math.Add) is an example of a shard that uses this data type for its input, output, and :Operand parameter.
1 2 3 4 5 | |
[info] [2022-07-22 21:20:18.771] [T-4568] [logging.cpp::55] [mywire] 5
[info] [2022-07-22 21:20:18.782] [T-4568] [logging.cpp::55] [mywire] 5
Int2¶
Type Int2 defines a vector of two Int type numbers.
Note
Has keyword int2 and alias Int2.
A vector can be thought of as a group or list of items that are considered together for processing.
An Int2 type value looks like this: (int2 3 -5).
(Math.Add) is an example of a shard that uses this data type for its input, output, and :Operand parameter.
1 2 | |
[info] [2022-07-22 21:22:26.381] [T-17748] [logging.cpp::55] [mywire] (10, 14)
Int3¶
Type Int3 defines a vector of three 32-bit signed integers.
Note
Has keyword int3 and alias Int3.
32 bits of memory for each number allows this data type to store integer values ranging from -2147483648 to +2147483647 (no decimals).
An Int3 type value looks like this: (int3 2 4 -4).
(Math.Add) is an example of a shard that uses this data type for its input, output, and :Operand parameter.
1 2 | |
[info] [2022-07-22 21:24:38.132] [T-25580] [logging.cpp::55] [mywire] (100, 100, 100)
Int4¶
Type Int4 is like type Int3 but is a vector of four 32-bit signed integers instead.
Note
Has keyword int4 and alias Int4.
An Int4 type value looks like this: (int4 1 -4 0 3).
(Math.Add) is an example of a shard that uses this data type for its input, output, and :Operand parameter.
1 2 3 | |
[info] [2022-07-22 21:27:58.115] [T-20884] [logging.cpp::55] [mywire] (9, 9, 9, 9)
Int8¶
Type Int8 defines a vector of eight 16-bit signed integers.
16 bits of memory for each number allows this data type to store integer values ranging from −32,768 to +32,767 (no decimals).
The shard (Math.Add) accepts Int8 as input and as its :Operand. The shard adds these up outputs the sum as another vector of 8 integers or Int8 data type.
Int16¶
Type Int16 defines a vector of sixteen 8-bit signed integers.
8 bits of memory for each number allows this data type to store integer values ranging from −128 to +127 (no decimals).
The shard (Math.Add) accepts Int16 as input and as its :Operand. The shard adds these up outputs the sum as another vector of 16 integers or Int16 data type.
None¶
Type None indicates that no data type is expected. This implies that no value is expected.
For example, None as one of the valid data types for :Max parameter in shard (RandomInt) means that setting a value for this parameter is not mandatory.
1 | |
(RandomInt) generates a random integer and the :Max parameter is the upper limit (not inclusive) of the value that can be generated. So it makes sense to have None as one of the valid types for this :Max parameter for cases when you do not want an upper limit on the random integer (though in this case the system will inherently set the upper limit to the maximum value a 64-bit signed integer can hold: 9,223,372,036,854,775,807).
1 2 3 4 5 | |
[info] [2022-07-22 13:45:03.282] [T-19992] [logging.cpp::55] [mywire] 4
[info] [2022-07-22 13:45:03.293] [T-19992] [logging.cpp::55] [mywire] 311828859
Object¶
Type Object is an opaque data type in Shards.
Opacity in a data type means that the structure of this kind of data is not defined in an interface and is visible only to shards that use this type. What this also implies is that the internal structure of this data type will vary from shard to shard.
For example, the :Socket parameter object of (WS.ReadString) is different from the output object of (GFX.DrawQueue), even though both are of type Object.
Path¶
Type Path is String type data that is expected to contain a valid path (your operating system or local machine) for loading resources like script files, images, audio files etc.
Note
Has keyword path and alias Path.
A valid Path type data string would look like this: "../../external/sample-models/Avocado.glb"
Note
For shards this type is the same as String type as far as type validations are concerned (when you execute your script Shards first checks the types before running your code). However, if the path-string passed is invalid, malformed, or missing the resource to be loaded, the shard will complain with an error message at runtime (i.e., when your code actually runs).
A shard that uses this type is (Process.Run). This shard takes a Path type in its :Executable parameter.
Set¶
Type Set is a collection of unique values.
It's different from other collections like Seq and Sequence, both of which can contain non-unique or duplicate items.
An example of a Set type data would be (22 3 378 4).
Seq¶
Type Seq is a collection of values that can be accessed sequentially (i.e., they're iterable).
Note
Has keyword seq.
Also called a sequence. An example of Seq type would be [7 2 54 42].
The shard (Take) works on this type. This shard can access Seq elements by their position.
1 2 | |
[info] [2022-07-26 22:24:48.918] [T-20928] [logging.cpp::55] [mywire] 54
Shard¶
The type Shard (also called ShardRef) represents a shard being passed as data.
This type is an important aspect of the homoiconicity feature (i.e., code/data interchangeability) in Shards.
Note
What's a shard?
The shard (ForEach) expects a value with the type Shard for its :Apply parameter (the other option being a sequence of Shard type values, i.e., a Wire type).
(ForEach) then applies this shard (or sequence of shards) on its input to transform it into its output.
[ Shard ]¶
When more that one shard is accepted it is indicated as a sequence of shards, any description can be turned into a sequence of shards by wrapping it with (-> ), for example:
1 2 3 4 | |
String¶
Type String represents string data (any data enclosed within double quotes).
Note
Has keyword string and alias String.
A String value looks like this: (string "Hello @Tom!"). It may also be represented without the keyword string, with just the data within double quotes: "Hello @Tom!".
An example of a shard that processes String type data is (String.ToUpper). This shard takes a String and converts it into its upper case version.
1 2 3 4 5 | |
[info] [2022-07-26 19:38:14.813] [T-18168] [logging.cpp::55] [mywire] Bytes: 0x20440058720 size: 11
Table¶
Type Table is a collection of key/value pairs.
Its also known as map, data dictionary, or associative array. An example of a Table type would be: {:key1 "Hello" :key2 "World"}.
1 2 3 | |
[info] [2022-07-26 22:46:17.194] [T-26104] [logging.cpp::55] [mywire] {k1: 123}
Wire¶
Type Wire represents a wire being passed as data.
Note
Has keyword Wire.
A Wire type thus consists of a sequence of shards (which make up the wire), their shared state (memory) context, name of the wire, and other properties that enable operations on the wire like scheduling it on a mesh, starting/stopping/pausing the wire, etc.
Note
What's a wire?
For example, the shard (Stop) accepts Wire type data in its :Wire parameter and stops that wire's execution if its currently running.