SHIP:Data Types

From Serious Documentation
Jump to: navigation, search

SHIP supports numerous data types for variables, constants, link variables, and port variables.

Note that, where relevant, all values within the SHIP Sail scripting and virtual machine environment are little Endian, regardless of the underlying MCU on the SIM.

Primitive Data Types

Boolean

Booleans SHIP are 1-bit values.

Data Type Description
Boolean A true or false value.

Byte

Bytes in SHIP are 8-bit signed numbers.

Data Type Description
Byte Signed number that fits in the range -128 to +127.

Short

Short Data Types in SHIP are 16-bit signed numbers.

Data Type Description
Short Signed number that fits in the range -32768 to +32767.

Integer

Integers in SHIP are 32-bit signed numbers.

Data Type Description
Integer Signed number that fits in the range -2^31 to +(2^31-1).

Float

Float Data Types are available in SHIPv5 and onwards, and are single precision IEEE754 floating point values.

Data Type Description
Float A single precision IEEE754 32-bit floating point value.

Double

Double Data Types are available in SHIPv5 and onwards, and are double precision IEEE754 floating point values.

Data Type Description
Double A double precision IEEE754 64-bit floating point value.

String

Stings in SHIP are a sequence of UTF8 characters terminated in an implicit end-of-string character.

Data Type Description
String A sequence of UTF8 characters terminated in an implicit end-of-string character.

Buffer

Buffers in SHIP are a sequence of bytes in memory.

Data Type Description
Buffer A sequence of bytes who length is determined by the capacity property.

Color

Colors in SHIP are 32-bit numbers in ARGB8888 format.

Data Type Description
Color A 32-bit value representing an ARGB8888-format color which includes 8-bits each of alpha (transparency), red, green, and blue.

Constants

Constant

Constants used in SHIP.

Constant Value Description
M_1_PI 0.31830988618379067154f 1/π
M_2_PI 0.63661977236758134308f 2/π
M_2_SQRTPI 1.12837916709551257390f 2/√π
M_E 2.7182818284590452354f e
M_LN10 2.30258509299404568402f ln 10; log_e 10; log of 10 base e
M_LN2 0.69314718055994530942f ln 2; log_e 2; log of 2 base e
M_LOG10E 0.43429448190325182765f log_10 e; log of e base 10
M_LOG2E 1.4426950408889634074f log_2 e; log of e base 2
M_MAX_BYTE 127 2^7 - 1
M_MAX_DIM 32767 Maximum dimension value
M_MAX_INTEGER 2,147,483,647 2^31 - 1
M_MAX_SHORT 32,767 2^15 -1
M_MAX_LONG 9,223,372,036,854,775,807 2^63 - 1
M_MIN_DIM -32,511 Minimum dimension value
M_MIN_INTEGER -2,147,483,648 -(2^31)
M_MIN_LONG -9,223,372,036,854,775,808 -(2^63)
M_MIN_SHORT -32,768 -(2^15)
M_NAN_DIM -32,768 Dimension unset
M_PI 3.14159265358979323846f π
M_PI_2 1.57079632679489661923f π/2
M_PI_4 0.78539816339744830962f π/4
M_SQRT1_2 0.70710678118654752440f 1/√2
M_SQRT_2 0.70710678118654752440f √2

Font Related Types

Codepoint

Data Type Description
Codepoint Unicode codepoints are 16-bit numbers, usually expressed in hexidecimal, that represent a unique character (e.g. 0x2122 for the ™ symbol). In SHIP there is no explicit Codepoint type, and Integers are commonly used to store/manipulate codepoints as unsigned values.

CodepointRange

Data Type Description
CodepointRange Sequence of Unicode codepoints to be included; expressed as Codepoint..Codepoint (inclusive).

For ease of use, SHIPTide contains Keywords for common groups of codepoints such as Basic ASCII, Accented Letters, Kanji, etc.

Font Family Info

FontFamilyInfo

List

Data Type Description
List Comma separated series of the same type.

Lists are most commonly used in SHIPTide as a list of References to other nodes' properties in a listener's listeningto property. This allows a single listener to listen for changes in multiple nodes' properties and execute the same script.

FONTSTYLE

FONTSTYLE

Pseudo Types

Certain data types are not really stand-alone data types, but rather special case uses of real data types. For example, the "Language" data type is not a stand-alone new data type, but rather a String with specific 4-letter construction.

HALIGN and VALIGN

The alignment properties of any Box Model or Text Model node position a box or text within the inner area of the parent.

Alignment Data Types
Data Type Description
HALIGN Horizontal alignment of a box model or text model node within its parent.
VALIGN Vertical alignment of a box model or text model node within its parent.

ByteOrder

The byte order type is used in linkset nodes to set the byte ordering of incoming/outgoing numeric types, as well as in various built-in functions such as bytesToString to determine the processing byte order of encoded data.

Byte Order Values
Data Type Description
ByteOrder Determines a byte flipping order in a number

Complex Data Types

Dimension

Data Type Description
Dimension A numeric type specifically within the pixel dimension range.

Node

Data Type Description
Node Reference to a node.

Time

Time Type Variables

Time type variables are a unique complex data type with several Integer subfields:

  • timevar.year -- the year, for example, 2016; this should be >= 2000
  • timevar.month -- the month 1..12 for Jan...Dec
  • timevar.day -- the day of the month 1..31
  • timevar.hour -- the hour in the day 0..23
  • timevar.minute -- the minute of the hour 0..59
  • timevar.second -- the second of the minute 0..59

In addition, there is an aggregate subfield:

  • timevar.value -- the number of seconds since 0:00:00 on January 1, 2000.

Auto-Translation Between .value and the other Subfields

When you assign the .value field with a number, the system will automatically translate this value to the other fields and vice versa. For example, assigning timevar.value = 10 will automatically set the year subfield to 2000, month to 1, day to 1, hour to 0, minute to 0, and seconds to 10. Subsequently changing the timevar.minute to 1 will then add 60 seconds to the value field which would then be 70.

Auto-Rollover on Subfields

The subfields can be assigned values outside their natural ranges. This will cause a rebalancing of the various fields to put them in compliance (if possible). For example, it is obvious you could set "timevar.month -= 1;" to go back one month in time. If, say, you were starting at February 20, timevar.month-- would change the time to January 20. The rest of the subfields would be unchanged except for the .value field.

However, subsequently subtracting 1 from the month causes a rollback to the prior year (December) as expected. You do not have to manually (e.g. if timevar == 1 <handle underrun> else <normal>). SHIP handles this automatically. So if you do a timevar.month-- when .month is 1, it will subtract one from the year and timevar.month will now be 12 as expected.

Similarly, assigning timevar.month to 13, for example, will cause the rebalance to timevar.month as 1 in the incremented year.

This capability makes it extremely easy to make date/time adjustments in the GUI, with the + and - buttons on each subfield simply implementing a -- or ++ on the subfield.

Events

All subfields of Time variables can cause events. For example, changing timevar.minute will cause any listener listeningto timevar.minute to wake up and run its associated script(s).

Multiple events are often generated simultaneously when subfields are adjusted. For example, changing the .value field will often fire multiple events across the other subfields because of the auto-translation from the .value field to the other subfields (.minute, etc.).

Similarly, auto-rollover can cause multiple events. For example, using a timevar.second-- when the date is Jan 1, 2001 at 00:00 will cause every subfield to change as the date is rolled back to the very last second of the year 2000.

Copying Time Variables

If you have two Time variables, you will generally want to copy the .value property. This atomically copies all the ingredients of the complex type at one time. For example if you have two Time variables named "foo" and "bar", you can use foo.value = bar.value, which will assign the time from bar to foo.

The shiptime System Variable

The shiptime system variable tracks the current system date/time and changes once per second during operation. For more information see shiptime.

Temperature (SHIPv4 Only)

In SHIPv4 the Temperature datatype is returned by the pcbTemperature portvar with a variable format configured by setting tempPrecision. In SHIPv5, this variable is renamed pcbTemp and is a normal Float.

Data Type Description
Temperature 16 bit fixed-point-integer interpreted as an 8-bit value in whole degrees followed by a tempPrecision-bit value in 1/256ths of a degree. Set shipCelsius to true for Celsius, or false for Fahrenheit.

Touch

Data Type Description
Touch Contains the type of the event, x coordinate, and y coordinate of the touch.

If the name of the touch port on your platform is "TOUCH0", access the information like so:

  • TOUCH0.event.e - contains the TOUCH.UP, TOUCH.DN, or TOUCH.MV event code
  • TOUCH0.event.x - contains the last x coordinate detected
  • TOUCH0.event.y - contains the last y coordinate detected
  • TOUCH0.event.value (or just TOUCH0.event) - used to detect whenever any sub-property (e, x, or y) changes.

Language

Language||A string of exactly 4 characters containing a 4-letter language code, for example "enUS" for English as used in the US.

PROTOCOL

PROTOCOL