Difference between revisions of "Recital Variables and Constants"

From Recital Documentation Wiki
Jump to: navigation, search
 
(37 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
==Recital Variables and Constants==
 
==Recital Variables and Constants==
 
===An Introduction to Recital Variables===
 
===An Introduction to Recital Variables===
 +
 
====Naming and Creating a Variable====
 
====Naming and Creating a Variable====
 +
Variable names must begin with a letter (A-Z, a-z) or an underscore (-), followed by any combination of letters, digits or underscores.  The variable name can be of any length, but only the first 32 characters are significant, so these must be unique.  Recital ignores the case of letters, so m_var, M_VAR, and m_VaR would all be treated as the same memory variable name.
  
Variable names must begin with a letter (A-Z, a-z) or an underscore (-), followed by any combination of letters, digits or underscores.  The variable name can be of any length, but only the first 32 characters are significant, so these must be unique.  Recital ignores the case of letters, so m_var, M_VAR, and m_VaR would all be treated as the same memory variable name.  The name given to a variable has no bearing on the type of data that is, or can be, stored in it.  In fact, the type of data stored in a particular variable can be changed at any time, although this needs to be carefully controlled so that inappropriate operations are not attempted. e.g.
+
The name given to a variable has no bearing on the type of data that is, or can be, stored in it.  By default, Recital is a loosely typed language and the type of data stored in a particular variable can be changed at any time.  Variables can be declared as a particular data type, and in this case only values of the correct data type can be assigned.
  
 
<code lang="recital">
 
<code lang="recital">
m_var = 1234
+
private nVar as numeric
m_var = 'a character value'
+
// Valid assignment
? m_var + 100
+
nVar = 1234
 +
// Throws error
 +
nVar = 'a character value'
 
</code>
 
</code>
  
Values can be assigned to memory variables without those memory variables having been pre-declared, but it is generally accepted that the pre-declaration of memory variables is good programming practice.  Variables can be declared as public, private or local and will be initialized as a logical false (.F.).
+
When [[SET STRICT|set strict is on]], variables must be declared before their value can be assigned. By default, [[SET STRICT|set strict is off]] and pre-declaration is not required.  Variables can be declared as public, private or local and will be initialized as a logical false (.F.).
  
 
<code lang="recital">
 
<code lang="recital">
public cVar1
+
public cVar1 as character, nVar1
private cVar2
+
private cVar2, nVar2 as numeric
local cVar3
+
local cVar3, nVar3, dVar3 as date
 
</code>
 
</code>
 
[[PUBLIC|Public]] variables are globally visible, they are accessible and can be changed from any part of an application.  If the application is run from the Interactive Prompt, then any public variables can still be accessed even after the application ends.  Any variables created at the Interactive Prompt are automatically created as public variables.
 
 
[[PRIVATE|Private]] variables are only visible within the declaring module (program, procedure, User Defined Function) and any modules called by that declaring module.  Any variables accessed within a module that are not pre-declared are automatically created as private variables.  When the module returns, then all of the memory variables and arrays that were declared by the private command are released.
 
 
[[LOCAL|Local]] variables are only visible within the declaring module and are released when the module returns. Local variables differ from private variables in that a local variable is not visible to lower level procedures or functions.
 
  
 
====Assigning a Value to a Variable====
 
====Assigning a Value to a Variable====
 
+
Values are assigned to memory variables at the time of declaration or using the [[STORE|store]] command or the equals = operator.
Values are assigned to memory variables using the [[STORE|store]] command, the equals = operator or the inline assignment [[Inline Assignment|:=]] operator.
+
  
 
<code lang="recital">
 
<code lang="recital">
store 'new value' to cVAR1
+
public cVar1 as character = 'start value'
cVAR1 = 'newer value'
+
private cVar1 as character = 'start value'
cVAR1 := 'newest value'
+
local cVar1 as character = 'start value'
 +
store 'new value' to cVar1
 +
cVar1 = 'newer value'
 
</code>
 
</code>
  
Line 38: Line 37:
  
 
<code lang="recital">
 
<code lang="recital">
store 'new value' to cVAR1, cVAR2
+
store 'new value' to cVar1, cVar2
 
</code>
 
</code>
  
 
====Accessing a Variable====
 
====Accessing a Variable====
====Changing the Type of a Variable====
+
Variables can be accessed using the variable name.  The memory variable pointer ''m->'' or ''m.'' prefix is optional.
  
 +
<code lang="recital">
 +
nVar = 1234
 +
echo nVar
 +
echo m.nVar
 +
echo m->nVar
 +
</code>
 +
 +
====Changing the Type of a Variable====
 
The [[TYPE()|type()]] or [[VARTYPE()|vartype()]] functions can be used to determine the data type of any variable.
 
The [[TYPE()|type()]] or [[VARTYPE()|vartype()]] functions can be used to determine the data type of any variable.
  
* All Variables
+
'''All Variables'''
** [[CAST()|cast()]] - perform data type conversion
+
* [[CAST()|cast()]] - perform data type conversion
** [[ETOS()|etos()]] - perform data type to string conversion
+
* Character Variables:
+
** [[Working With String Data in Recital#String Conversion Functions|String Conversion Functions]]
+
* Date and Datetime Variables:
+
** [[Working With Date and Time Data in Recital#Date and Time Conversion Functions|Date and Time Conversion Functions]]
+
* Numeric Variables
+
** [[Working With Numeric Data in Recital#Numeric Conversion Functions|Numeric Conversion Functions]]
+
* Logical Variables
+
** [[LTOS()|ltos()]] - perform logical to string conversion
+
  
====Checking Whether a Variable Exists====
+
<pre>
 +
expression = cast(expression as expression AS datatype as character [, width as numeric [, precision as numeric]] [null | not null])
 +
</pre>
  
 +
* [[ETOS()|etos()]] - perform data type to string conversion
 +
 +
<pre>
 +
character = etos(expression as expression)
 +
</pre>
 +
 +
* [[TOSTRING()|tostring()]] - perform data type to string conversion
 +
 +
<pre>
 +
character = tostring(expression as expression [, length as numeric)
 +
</pre>
 +
 +
'''Character Variables:'''
 +
 +
Please see [[Working With String Data in Recital#String Conversion Functions|String Conversion Functions]] in the separate chapter ''Working With String Data in Recital''.
 +
 +
'''Date and Datetime Variables:'''
 +
 +
Please see [[Working With Date and Time Data in Recital#Date and Time Conversion Functions|Date and Time Conversion Functions]] in the separate chapter ''Working With Date and Time Data in Recital''.
 +
 +
'''Numeric Variables'''
 +
 +
Please see [[Working With Numeric Data in Recital#Numeric Conversion Functions|Numeric Conversion Functions]] in the separate chapter ''Working With Numeric Data in Recital''.
 +
 +
'''Logical Variables'''
 +
* [[LTOS()|ltos()]] - perform logical to string conversion
 +
 +
====Checking Whether a Variable Exists====
 
The [[ISSET()|isset()]] function can be used to check whether a variable exists.
 
The [[ISSET()|isset()]] function can be used to check whether a variable exists.
  
 
<code lang="recital">
 
<code lang="recital">
if isset(m_var)
+
if isset(nVar)
   // m_var exists
+
   // nVar exists
 
endif
 
endif
 
</code>
 
</code>
  
 
====Variable Scope====
 
====Variable Scope====
 +
[[PUBLIC|Public]] variables are globally visible, they are accessible and can be changed from any part of an application.  If the application is run from the Interactive Prompt, then any public variables can still be accessed even after the application ends.  Any variables created at the Interactive Prompt are automatically created as public variables.
  
...
+
[[PRIVATE|Private]] variables are only visible within the declaring module (program, procedure, User Defined Function) and any modules called by that declaring module. Any variables accessed within a module that are not pre-declared are automatically created as private variables. When the module returns, then all of the memory variables and arrays that were declared by the private command are released.
 +
 
 +
[[LOCAL|Local]] variables are only visible within the declaring module and are released when the module returns. Local variables differ from private variables in that a local variable is not visible to lower level procedures or functions.
  
 
To manually release a memory variable, use the [[UNSET()|unset()]] function:
 
To manually release a memory variable, use the [[UNSET()|unset()]] function:
  
 
<code lang="recital">
 
<code lang="recital">
if isset(m_var)
+
if isset(nVar)
   unset(m_var)
+
   unset(nVar)
 
endif
 
endif
 
</code>
 
</code>
Line 82: Line 113:
 
===Understanding Recital Variable Types===
 
===Understanding Recital Variable Types===
 
====Recital Character Variables====
 
====Recital Character Variables====
 +
Character variables contain a string of ASCII characters up to 65535 characters in length.
 +
 +
To prevent non-character values being assigned to a character variable, use the 'as character' clause at the time of declaration. 
 +
 +
The [[TYPE()|type()]] function returns 'C' for character variables and the [[IS_STRING()|is_string()]] function returns .T. (true).
 +
 +
<code lang="recital">
 +
private cVar as character = "Hello World"
 +
? type("cVar")
 +
C
 +
? is_string(cVar)
 +
.T.
 +
</code>
 +
 
====Recital Numeric Variables====
 
====Recital Numeric Variables====
 +
Numeric variables contain a signed or unsigned integer number of up to 16 digits (0-9) or floating point number of up to 25 digits (9 are reserved for decimal places) and one decimal point.
 +
 +
To prevent non-numeric values being assigned to a numeric variable, use the 'as numeric' clause at the time of declaration. 
 +
 +
The [[TYPE()|type()]] function returns 'N' for numeric variables and the [[IS_FLOAT()|is_float()]] and [[IS_INT()|is_int()]] functions return .T. (true).
 +
 +
<code lang="recital">
 +
private nVar as numeric = -12.34
 +
? type("nVar")
 +
N
 +
? is_float(nVar)
 +
.T.
 +
? is_int(nVar)
 +
.T.
 +
</code>
 +
 
====Recital Date Variables====
 
====Recital Date Variables====
 +
Date variables contain a valid combination of digits and separators in a format determined by the [[SET DATE|set date]] and [[SET CENTURY|set century]] commands.
 +
 +
To prevent non-date values being assigned to a date variable, use the 'as date' clause at the time of declaration. 
 +
 +
The [[TYPE()|type()]] function returns 'D' for date variables.
 +
 +
<code lang="recital">
 +
private dVar as date = date()
 +
? type("dVar")
 +
D
 +
</code>
 +
 
====Recital Logical Variables====
 
====Recital Logical Variables====
 +
Logical variable contain either .T. for true or .F. for false.
 +
 +
To prevent non-logical values being assigned to a logical variable, use the 'as logical' clause at the time of declaration. 
 +
 +
The [[TYPE()|type()]] function returns 'L' for logicals.
 +
 +
<code lang="recital">
 +
private lVar as logical = .T.
 +
? type("lVar")
 +
L
 +
</code>
 +
 
====Recital Datetime Variables====
 
====Recital Datetime Variables====
 +
Datetime variables contain a valid combination of digits and separators in a format determined by the [[SET DATE|set date]] and [[SET CENTURY|set century]] commands.
 +
 +
To prevent non-datetime values being assigned to a datetime variable, use the 'as datetime' clause at the time of declaration. 
 +
 +
The [[TYPE()|type()]] function returns 'T' for datetime variables.
 +
 +
<code lang="recital">
 +
private tVar as datetime = datetime()
 +
? type("tVar")
 +
T
 +
</code>
 +
 
====Recital Currency Variables====
 
====Recital Currency Variables====
 +
Currency variables contain monetary numeric values.
 +
 +
To prevent non-currency values being assigned to a currency variable, use the 'as currency' clause at the time of declaration. 
 +
 +
The [[TYPE()|type()]] function returns 'Y' for currency variables.
 +
 +
<code lang="recital">
 +
private yVar as currency = $99.99
 +
? type("yVar")
 +
Y
 +
</code>
 +
 
===Recital Constants===
 
===Recital Constants===
 
====Character Constants====
 
====Character Constants====
Line 92: Line 201:
 
A string of ASCII characters up to 65535 characters in length.
 
A string of ASCII characters up to 65535 characters in length.
  
Delimited by double quotes "", or single quotes.
+
Delimited by double quotes "", or single quotes &#145;&#146;.
  
 
<code lang="recital">
 
<code lang="recital">
[hello]
 
 
'goodbye'
 
'goodbye'
 
"RECITAL"
 
"RECITAL"
Line 105: Line 213:
  
 
====Numeric Constants====
 
====Numeric Constants====
An integer number of up to 16 digits (0-9) or a floating point number of up to 25 digits (9 are reserved for decimal places) and one decimal point.
+
A signed or unsigned integer number of up to 16 digits (0-9) or floating point number of up to 25 digits (9 are reserved for decimal places) and one decimal point.
  
 
<code lang="recital">
 
<code lang="recital">

Latest revision as of 14:08, 4 November 2014

Recital Variables and Constants

An Introduction to Recital Variables

Naming and Creating a Variable

Variable names must begin with a letter (A-Z, a-z) or an underscore (-), followed by any combination of letters, digits or underscores. The variable name can be of any length, but only the first 32 characters are significant, so these must be unique. Recital ignores the case of letters, so m_var, M_VAR, and m_VaR would all be treated as the same memory variable name.

The name given to a variable has no bearing on the type of data that is, or can be, stored in it. By default, Recital is a loosely typed language and the type of data stored in a particular variable can be changed at any time. Variables can be declared as a particular data type, and in this case only values of the correct data type can be assigned.

private nVar as numeric
// Valid assignment
nVar = 1234
// Throws error
nVar = 'a character value'

When set strict is on, variables must be declared before their value can be assigned. By default, set strict is off and pre-declaration is not required. Variables can be declared as public, private or local and will be initialized as a logical false (.F.).

public cVar1 as character, nVar1
private cVar2, nVar2 as numeric
local cVar3, nVar3, dVar3 as date

Assigning a Value to a Variable

Values are assigned to memory variables at the time of declaration or using the store command or the equals = operator.

public cVar1 as character = 'start value'
private cVar1 as character = 'start value'
local cVar1 as character = 'start value'
store 'new value' to cVar1
cVar1 = 'newer value'

Note that the store command can assign a value to more than one memory variable in a single command.

store 'new value' to cVar1, cVar2

Accessing a Variable

Variables can be accessed using the variable name. The memory variable pointer m-> or m. prefix is optional.

nVar = 1234
echo nVar
echo m.nVar
echo m->nVar

Changing the Type of a Variable

The type() or vartype() functions can be used to determine the data type of any variable.

All Variables

  • cast() - perform data type conversion
expression = cast(expression as expression AS datatype as character [, width as numeric [, precision as numeric]] [null | not null])
  • etos() - perform data type to string conversion
character = etos(expression as expression)
  • tostring() - perform data type to string conversion
character = tostring(expression as expression [, length as numeric)

Character Variables:

Please see String Conversion Functions in the separate chapter Working With String Data in Recital.

Date and Datetime Variables:

Please see Date and Time Conversion Functions in the separate chapter Working With Date and Time Data in Recital.

Numeric Variables

Please see Numeric Conversion Functions in the separate chapter Working With Numeric Data in Recital.

Logical Variables

  • ltos() - perform logical to string conversion

Checking Whether a Variable Exists

The isset() function can be used to check whether a variable exists.

if isset(nVar)
  // nVar exists
endif

Variable Scope

Public variables are globally visible, they are accessible and can be changed from any part of an application. If the application is run from the Interactive Prompt, then any public variables can still be accessed even after the application ends. Any variables created at the Interactive Prompt are automatically created as public variables.

Private variables are only visible within the declaring module (program, procedure, User Defined Function) and any modules called by that declaring module. Any variables accessed within a module that are not pre-declared are automatically created as private variables. When the module returns, then all of the memory variables and arrays that were declared by the private command are released.

Local variables are only visible within the declaring module and are released when the module returns. Local variables differ from private variables in that a local variable is not visible to lower level procedures or functions.

To manually release a memory variable, use the unset() function:

if isset(nVar)
  unset(nVar)
endif

Understanding Recital Variable Types

Recital Character Variables

Character variables contain a string of ASCII characters up to 65535 characters in length.

To prevent non-character values being assigned to a character variable, use the 'as character' clause at the time of declaration.

The type() function returns 'C' for character variables and the is_string() function returns .T. (true).

private cVar as character = "Hello World"
? type("cVar")
C
? is_string(cVar)
.T.

Recital Numeric Variables

Numeric variables contain a signed or unsigned integer number of up to 16 digits (0-9) or floating point number of up to 25 digits (9 are reserved for decimal places) and one decimal point.

To prevent non-numeric values being assigned to a numeric variable, use the 'as numeric' clause at the time of declaration.

The type() function returns 'N' for numeric variables and the is_float() and is_int() functions return .T. (true).

private nVar as numeric = -12.34
? type("nVar")
N
? is_float(nVar)
.T.
? is_int(nVar)
.T.

Recital Date Variables

Date variables contain a valid combination of digits and separators in a format determined by the set date and set century commands.

To prevent non-date values being assigned to a date variable, use the 'as date' clause at the time of declaration.

The type() function returns 'D' for date variables.

private dVar as date = date()
? type("dVar")
D

Recital Logical Variables

Logical variable contain either .T. for true or .F. for false.

To prevent non-logical values being assigned to a logical variable, use the 'as logical' clause at the time of declaration.

The type() function returns 'L' for logicals.

private lVar as logical = .T.
? type("lVar")
L

Recital Datetime Variables

Datetime variables contain a valid combination of digits and separators in a format determined by the set date and set century commands.

To prevent non-datetime values being assigned to a datetime variable, use the 'as datetime' clause at the time of declaration.

The type() function returns 'T' for datetime variables.

private tVar as datetime = datetime()
? type("tVar")
T

Recital Currency Variables

Currency variables contain monetary numeric values.

To prevent non-currency values being assigned to a currency variable, use the 'as currency' clause at the time of declaration.

The type() function returns 'Y' for currency variables.

private yVar as currency = $99.99
? type("yVar")
Y

Recital Constants

Character Constants

A string of ASCII characters up to 65535 characters in length.

Delimited by double quotes "", or single quotes ‘’.

'goodbye'
"RECITAL"
"1234.56"
"12/12/2009"

The type() function returns 'C' for character strings.

Numeric Constants

A signed or unsigned integer number of up to 16 digits (0-9) or floating point number of up to 25 digits (9 are reserved for decimal places) and one decimal point.

1234
1234.56

The type() function returns 'N' for numerics.

Date Constants

A combination of digits and separators delimited by curly braces {}. The format is determined by the set date and set century commands.

// set date is BRITISH, set century is OFF
{21/01/09}
// set date is AMERICAN, set century is ON
{01/21/2009}
// set date is GERMAN, set century is ON
{21/01/2009}
// set date is JAPAN, set century is ON
{2009/21/01}

The type() function returns 'D' for dates.

Logical Constants

A choice of two values, .T. for true, .F. for false

The type() function returns 'L' for logicals.

Datetime Constants

A combination of digits and separators delimited by curly braces {}. The format is determined by the set date and set century commands.

// set date is BRITISH, set century is OFF
{21/01/09 02:11:12 PM}
// set date is AMERICAN, set century is ON
{01/21/2009 05:09:09 AM}
// set date is GERMAN, set century is ON
{21/01/2009 11:30:00 PM}
// set date is JAPAN, set century is ON
{2009/21/01 12:10:10 AM}

The type() function returns 'T' for datetimes.

Currency Constants

A monetary value prefixed with a dollar sign, '$', and consisting of up to 9 digits and 4 decimal places.

$123456789.1234
$99

The type() function returns 'Y' for currency values.