signal_datagram

٤ سبتمبر ٢٠٢٣

The purpose of this library is to split and merge an integer into useful pieces of information that can easily handled and plotted.
The basic piece of information is one word. Depending on the underlying numerical system a word can be a bit, octal, digit, nibble, or byte.
The user can define channels. Channels are named groups of words. Multiple words can be combined to increase the value range of a channel.
A datagram is a description of the user-defined channels in an also user-defined numeric system that also contains all runtime information that is necessary to split and merge the integer.

This library simplifies the communication between two scripts by allowing the user to define the same datagram in both scripts.
On the sender's side, the channel values can be merged into one single integer value called signal. This signal can be 'emitted' using the plot function. The other script can use the 'input.source' function to receive that signal.
On the receiver's end based on the same datagram, the signal can be split into several channels. Each channel has the piece of information that the sender script put.

In the example of this library, we use two channels and we have split the integer in half. However, the user can add new channels, change them, and give meaning to them according to the functionality he wants to implement and the type of information he wants to communicate.

Nowadays many 'input.source' calls are allowed to pass information between the scripts, When that is not a price or a floating value, this library is very useful.
The reason is that most of the time, the convention that is used is not clear enough and it is easy to do things the wrong way or break them later on.
With this library validation checks are done during the initialization minimizing the possibility of error due to some misconceptions.

Library "signal_datagram"
Conversion of a datagram type to a signal that can be "send" as a single value from an indicator to a strategy script

method init(this, positions, maxWords)
  init - Initialize if the word positons array with an empty array
  Namespace types: WordPosArray
  Parameters:
    this (WordPosArray): - The word positions array object
    positions (int[]): - The array that contains all the positions of the worlds that shape the channel
    maxWords (int): - The maximum words allowed based on the span
  Returns: The initialized object

method init(this)
  init - Initialize if the channels word positons map with an empty map
  Namespace types: ChannelDesc
  Parameters:
    this (ChannelDesc): - The channels' descriptor object
  Returns: The initialized object

method init(this, numericSystem, channelDesc)
  init - Initialize if the datagram
  Namespace types: Datagram
  Parameters:
    this (Datagram): - The datagram object
    numericSystem (simple string): - The numeric system of the words to be used
    channelDesc (ChannelDesc): - The channels descriptor that contains the positions of the words that each channel consists of
  Returns: The initialized object

method add_channel(this, name, positions)
  add_channel - Add a new channel descriptopn with its name and its corresponding word positons to the map
  Namespace types: ChannelDesc
  Parameters:
    this (ChannelDesc): - The channels' descriptor object to update
    name (simple string)
    positions (int[])
  Returns: The initialized object

method set_signal(this, value)
  set_signal - Set the signal value
  Namespace types: Datagram
  Parameters:
    this (Datagram): - The datagram object to update
    value (int): - The signal value to set

method get_signal(this)
  get_signal - Get the signal value
  Namespace types: Datagram
  Parameters:
    this (Datagram): - The datagram object to query
  Returns: The value of the signal in digits

method set_signal_sign(this, sign)
  set_signal_sign - Set the signal sign
  Namespace types: Datagram
  Parameters:
    this (Datagram): - The datagram object to update
    sign (int): - The negative -1 or positive 1 sign of the underlying value

method get_signal_sign(this)
  get_signal_sign - Get the signal sign
  Namespace types: Datagram
  Parameters:
    this (Datagram): - The datagram object to query
  Returns: The sign of the signal value -1 if it is negative and 1 if it is possitive

method get_channel_names(this)
  get_channel_names - Get an array of all channel names
  Namespace types: Datagram
  Parameters:
    this (Datagram)
  Returns: An array that has all the channel names that are used by the datagram

method set_channel_value(this, channelName, value)
  set_channel_value - Set the value of the channel
  Namespace types: Datagram
  Parameters:
    this (Datagram): - The datagram object to update
    channelName (simple string): - The name of the channel to set the value to. Then name should be as described int the schemas channel descriptor
    value (int): - The channel value to set

method set_all_channels_value(this, value)
  set_all_channels_value - Set the value of all the channels
  Namespace types: Datagram
  Parameters:
    this (Datagram): - The datagram object to update
    value (int): - The channel value to set

method set_all_channels_max_value(this)
  set_all_channels_value - Set the value of all the channels
  Namespace types: Datagram
  Parameters:
    this (Datagram): - The datagram object to update

method get_channel_value(this, channelName)
  get_channel_value - Get the value of the channel
  Namespace types: Datagram
  Parameters:
    this (Datagram): - The datagram object to query
    channelName (simple string)
  Returns: Digit group of words (bits/octals/digits/nibbles/hexes/bytes) found at the channel accodring to the schema

WordDesc
  Fields:
    numericSystem (series__string)
    span (series__integer)

WordPosArray
  Fields:
    positions (array__integer)

ChannelDesc
  Fields:
    map (map__series__string:|WordPosArray|#OBJ)

Schema
  Fields:
    wordDesc (|WordDesc|#OBJ)
    channelDesc (|ChannelDesc|#OBJ)

Signal
  Fields:
    value (series__integer)
    isNegative (series__bool)
    words (array__integer)

Datagram
  Fields:
    schema (|Schema|#OBJ)
    signal (|Signal|#OBJ)

١١ أكتوبر ٢٠٢٣

ملاحظات الأخبار

v2
Added some documentation

٢٥ فبراير

ملاحظات الأخبار

v3
Some minor optimizations using `const` variables where it was possible

١٤ سبتمبر

ملاحظات الأخبار

v4

• Use enum for numeric system
  
• Updated documentation