Class Var

Introduction

This class provides a more type-agnostic way to box primitives in Synergy/DE. Additionally, it provides methods and operator overloads to help prevent the need to unbox or cast the value.

Contents

  1. Introduction
  2. Contents
  3. Explanation of symbols used
  4. Member reference
    1. add - perform addition
    2. AsAlpha - convert a Var to alpha
    3. AsDecimal - convert a Var to decimal
    4. AsInteger - convert a Var to integer
    5. Box - create a Var
    6. compare - conditional comparisons
    7. decrement - decrement the value
    8. divide - perform division
    9. increment - increment the value
    10. match - Regular Expression matching
    11. modulo - modulo operation
    12. multiply - perform multiplication
    13. negate - perform negation
    14. replace - regular expression replacement
    15. replace - split on regular expression
    16. subtract - perform subtraction
    17. ToHtml - convert to an HTML-friendly string
    18. truth - test for truth

Explanation of symbols used

Words in italics indicate an instance of a class. The word corresponds to the class name, except where more than one instance is represented in the same statement. In that case a number (2, 3, etc.) is appended to the class name.

Words in normal typeface are to be taken literally (required punctuation, class name in a static reference, method name, etc.)

The symbol => is used to separate an expression (on the left) from its return value (on the right).

An ellipsis (...) indicates that the previous argument may be repeated any number of times. The description will indicate whether one instance is required.

Member reference

method add, operator +

var.add(operand) => var2
var + operand => var2
operand + var => var2

Adds var and operand, yielding a new Var. The operand may be another Var or a primitive of any type. If primitive, operand will be boxed as a Var of the appropriate type before computing the result according to the rules below.

When adding Vars of the same type, the result is also of that type. When adding VarInt and VarDec, the result is VarDec. When adding any type to VarAlpha, the result is VarAlpha. For VarAlpha, addition means string concatenation. For VarInt and VarDec, it means numeric addition.

methods AsAlpha, ToString, explicit cast

var.AsAlpha() => a
(a)var => a
(string)var => string
var.ToString() => string

Converts a Var to alpha or string, regardless of its original type.

methods AsDecimal, explicit cast

var.AsDecimal() => decimal
(decimal)var => decimal

Converts a Var to decimal, regardless of its original type.

If var is a VarAlpha containing non-decimal characters, the result will be 0.

methods AsInteger, explicit cast

var.AsInteger() => int
(i)var => int

Converts a Var to integer, regardless of its original type.

If var is a VarDec containing a non-integer portion, it will be rounded or truncated according to the rules in effect for %integer(). If var is a VarAlpha containing non-numeric characters, the result will be 0.

method Box, explicit cast

Var.Box(primitive) => var
(Var)primitive => var

Creates a Var that boxes primitive, which may be an integer, decimal, or alpha (including string) expression. The true type of var will be VarInt, VarDec, or VarAlpha, depending on the primitive's type, but for all practical purposes you should treat it as Var.

For Var.Box, if you pass a non-primitive object, it will be returned as is. The same does not occur for casting as (Var).

method compare, conditional operators

var.compare(operand) => i

Compares var and operand, yielding an integer value of -1 for less than, 0 for equal, and 1 for greater than. Because Var uses the Comparable mixin, this method is automatically invoked whenever a Var is one of the operands in a conditional expression using .eq. (==), .ne. (!=), .gt. (>), .lt. (<), .ge. (>=), or .le. (<=). If the other operand is not a Var, it will be automatically boxed as a Var of the appropriate type before comparing.

When Vars of different types are compared, VarInt may be promoted to VarDec, and either may be promoted to VarAlpha.

method decrement, operator decr

var.decrement() => var
decr var

Decrements the value of a Var in place, returning that same Var. For integer and decimal Vars, subtracts 1 from the value. For alphameric, subtracts 1 from the ASCII value of the last character. If that character is already char(1), it is removed from the end of the string. If the string is already empty, no change occurs.

method divide, operator /

var.divide(operand) => var2
var / operand => var2
operand / var => var2

Divides var and operand, yielding a new Var. The operand may be another Var or a primitive of any type. If primitive, operand will be boxed as a Var of the appropriate type before computing the result according to the rules below.

When dividing Vars of the same type, the result is also of that type. When the types differ, both operands are cast as decimal (because string division doesn't make sense).

Note that attempting to divide by zero (or a non-decimal string) will result in a catchable runtime exception.

method increment, operator incr

var.increment() => var
incr var

Increments the value of a Var in place, returning that same Var. For integer and decimal Vars, adds 1 to the value. For alphameric, adds 1 to the ASCII value of the last character. If that character is already char(255) or the string is empty, appends char(1).

method match

var.match(regex) => matchdata

Performs regex.match(var.ToString()), which yields a MatchData object. See Regex.match for details.

method modulo

var.modulo(operand) => var2

Creates a new VarInt containing the result of var modulo operand, where both var and operand are treated as integer.

The operand may be another Var or any primitive type. If primitive, it will be boxed as a Var before casting it as integer.

Modulo is defined as the remainder from integer division of var by operand.

method multiply, operator *

var.multiply(operand) => var2
var * operand => var2
operand * var => var2

Multiplies var and operand, yielding a new Var. The operand may be another Var or a primitive of any type. If primitive, operand will be boxed as a Var of the appropriate type before computing the result according to the rules below.

When multiplying Vars of the same type, the result is also of that type. When multiplying VarInt and VarDec, the result is VarDec.

When one of the operands is VarAlpha, the other operand will be cast as integer (even if it's VarAlpha) to perform string multiplication. The alpha operand will be repeated that number of times.

method negate, operator -

var.negate() => var2
-var => var2

Negates var, yielding a new Var of the same type.

The result for a VarAlpha will always be "", which is the same as ("" - var).

method replace

var.replace(regex, object) => var2
Performs Regular Expression replacement of the portion of the string representation of var that matches regex with the string representation of object, yielding a new VarAlpha. If object is primitive, it will be boxed as a Var before being extracted as a string. For the rules of Regular Expression replacement, see Regex.replace.

method split

var.split(regex) => ls
var.split(regex, boolean) => ls
Splits the alphanumeric representation of var at regex. See Regex.split for details.

method subtract, operator -

var.subtract(operand) => var2
var - operand => var2
operand - var => var2

Subtracts var and operand, yielding a new Var. The operand may be another Var or a primitive of any type. If primitive, operand will be boxed as a Var of the appropriate type before computing the result according to the rules below.

When subtracting Vars of the same type, the result is also of that type. When subtracting VarInt and VarDec, the result is VarDec. When subtracting from VarAlpha, string subtraction is performed -- i.e., the first occurrence (if any) of the second operand is removed from the first. When subtracting VarAlpha from another type, the VarAlpha is first converted to decimal.

method ToHtml

var.ToHtml() => string
Converts the string representation of var (see ToString) to an HTML-friendly format. Specifically, tabs and spaces are converted to the appropriate number of "&nbsp;", ampersands are converted to "&amp;", > and < are converted to "&gt;" and "&lt;", respectively, ' is converted to "&apos;" and " is converted to "&quot;". The resulting string will be no more than 65535 characters in length.

method truth, boolean operators

var.truth() => boolean
var => boolean

Allows var to be tested for truth. This occurs implictly in Synergy/DE when, for instance, an object reference is the sole operand in a conditional expression. Because Var uses the Boolean mixin, truth is automatically provided in response to .not. (!), .and. (&&), .or. (||), and .xor. when a Var is one or more of the operands.

The test for truth is consistent with standard DIBOL types: VarInt and VarDec are true if non-zero, VarAlpha is true if non-blank with length greater than 0.