diff options
Diffstat (limited to 'helpcontent2/source/text/sbasic/shared/01020100.xhp')
| -rw-r--r-- | helpcontent2/source/text/sbasic/shared/01020100.xhp | 266 |
1 files changed, 266 insertions, 0 deletions
diff --git a/helpcontent2/source/text/sbasic/shared/01020100.xhp b/helpcontent2/source/text/sbasic/shared/01020100.xhp new file mode 100644 index 000000000..ed5ce1eaa --- /dev/null +++ b/helpcontent2/source/text/sbasic/shared/01020100.xhp @@ -0,0 +1,266 @@ +<?xml version="1.0" encoding="UTF-8"?> +<helpdocument version="1.0"> +<!-- + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + * This file incorporates work covered by the following license notice: + * + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed + * with this work for additional information regarding copyright + * ownership. The ASF licenses this file to you under the Apache + * License, Version 2.0 (the "License"); you may not use this file + * except in compliance with the License. You may obtain a copy of + * the License at http://www.apache.org/licenses/LICENSE-2.0 . +--> + +<meta> + <topic id="textsbasicshared01020100xml" indexer="include" status="PUBLISH"> + <title id="tit" xml-lang="en-US">Using Variables</title> + <filename>/text/sbasic/shared/01020100.xhp</filename> + </topic> +</meta> + +<body> + +<section id="variable"> +<bookmark xml-lang="en-US" branch="index" id="bm_id3149346"> + <bookmark_value>names of variables</bookmark_value> + <bookmark_value>variables; using</bookmark_value> + <bookmark_value>types of variables</bookmark_value> + <bookmark_value>declaring variables</bookmark_value> + <bookmark_value>values;of variables</bookmark_value> + <bookmark_value>literals;date</bookmark_value> + <bookmark_value>literals;integer</bookmark_value> + <bookmark_value>literals;integer</bookmark_value> + <bookmark_value>literals;floating point</bookmark_value> + <bookmark_value>constants</bookmark_value> + <bookmark_value>arrays;declaring</bookmark_value> + <bookmark_value>defining;constants</bookmark_value> +</bookmark> + + +<h1 id="hd_id3149346"><link href="text/sbasic/shared/01020100.xhp" name="Using Variables">Using Variables</link></h1> +<paragraph id="par_id3154346" role="paragraph" xml-lang="en-US">The following describes the basic use of variables in $[officename] Basic.</paragraph> +</section> + +<h2 id="hd_id3153361">Naming Conventions for Variable Identifiers</h2> +<paragraph id="par_id3148797" role="paragraph" xml-lang="en-US">A variable name can consist of a maximum of 255 characters. The first character of a variable name <emph>must</emph> be a letter A-Z or a-z. Numbers can also be used in a variable name, but punctuation symbols and special characters are not permitted, with exception of the underscore character ("_"). In $[officename] Basic variable identifiers are not case-sensitive. Variable names may contain spaces but must be enclosed in square brackets if they do.</paragraph> +<paragraph id="par_id3156422" role="paragraph" xml-lang="en-US">Examples for variable identifiers:</paragraph> + +<bascode> + <paragraph id="par_idm1341272896" role="bascode">MyNumber=5 'Correct'</paragraph> + <paragraph id="par_idm1341267456" role="bascode">MyNumber5=15 'Correct'</paragraph> + <paragraph id="par_idm1341262016" role="bascode">MyNumber_5=20 'Correct'</paragraph> + <paragraph id="par_idm1341256576" role="bascode">My Number=20 'Not valid, variable with space must be enclosed in square brackets'</paragraph> + <paragraph id="par_idm1341251088" role="bascode">[My Number]=12 'Correct'</paragraph> + <paragraph id="par_idm1341245648" role="bascode">DéjàVu=25 'Not valid, special characters are not allowed'</paragraph> + <paragraph id="par_idm1341240176" role="bascode">5MyNumber=12 'Not valid, variable may not begin with a number'</paragraph> + <paragraph id="par_idm1341234704" role="bascode">Number,Mine=12 'Not valid, punctuation marks are not allowed'</paragraph> +</bascode> + +<h2 id="hd_id3146317">Declaring Variables</h2> +<paragraph id="par_id3150299" role="paragraph" xml-lang="en-US">In $[officename] Basic you don't need to declare variables explicitly. A variable declaration can be performed with the <emph>Dim</emph> statement. You can declare more than one variable at a time by separating the names with a comma. To define the variable type, use either a type-declaration sign after the name, or the appropriate key word. </paragraph> +<paragraph id="par_id3154118" role="paragraph" xml-lang="en-US">Examples for variable declarations:</paragraph> + +<bascode> + <paragraph id="par_idm1341222320" role="bascode">Dim a$ 'Declares the variable "a" as a String'</paragraph> + <paragraph id="par_idm1341216864" role="bascode">Dim a As String 'Declares the variable "a" as a String'</paragraph> + <paragraph id="par_idm1341211408" role="bascode">Dim a$, b As Integer 'Declares one variable as a String and one as an Integer'</paragraph> + <paragraph id="par_idm1341205936" role="bascode">Dim c As Boolean 'Declares c as a Boolean variable that can be TRUE or FALSE'</paragraph> +</bascode> + +<warning id="par_id3144770">Once you have declared a variable as a certain type, you cannot declare the variable under the same name again as a different type!</warning> + +<paragraph role="paragraph" id="par_id421619551219763">When you declare multiple variables in a single line of code you need to specify the type of each variable. If the type of a variable is not explicitly specified, then Basic will assume that the variable is of the <emph>Variant</emph> type.</paragraph> +<bascode> + <paragraph role="bascode" id="bas_id321619555442706">' Both variables "a" and "b" are of the Integer type</paragraph> + <paragraph role="bascode" localize="false" id="bas_id511619551568768">Dim a As Integer, b As Integer</paragraph> + <paragraph role="bascode" id="bas_id451619555463988">' Variable "c" is a Variant and "d" is an Integer</paragraph> + <paragraph role="bascode" localize="false" id="bas_id511619551568144">Dim c, d As Integer</paragraph> + <paragraph role="bascode" id="bas_id161619555482237">' A variable can also be explicitly declared as a Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id601619552527089">Dim e As Variant, f As Double</paragraph> +</bascode> +<note id="par_id521619551687371">The <emph>Variant</emph> type is a special data type that can store any kind of value. To learn more, refer to the section <link href="text/sbasic/shared/01020100.xhp#VariantTypeH2" name="Variant Type">The Variant type</link> below.</note> + +<h3 id="hd_id3149331">Forcing Variable Declarations</h3> +<paragraph id="par_id3149443" role="paragraph" xml-lang="en-US">To force declaration of variables, use the following command:</paragraph> +<bascode> +<paragraph id="par_idm1341182432" role="bascode" localize="false" xml-lang="en-US">Option Explicit</paragraph> +</bascode> +<paragraph id="par_id3155072" role="paragraph" xml-lang="en-US">The <emph>Option Explicit</emph> statement has to be the first line in the module, before the first SUB. Generally, only arrays need to be declared explicitly. All other variables are declared according to the type-declaration character, or - if omitted - as the default type <emph>Single</emph>.</paragraph> + +<h2 id="hd_id3154614">Variable Types</h2> +<paragraph id="par_id3155383" role="paragraph" xml-lang="en-US">$[officename] Basic supports four variable classes:</paragraph> + +<list type="unordered"> + <listitem> + <paragraph id="par_id3153972" role="listitem" xml-lang="en-US"> <emph>Numeric</emph> variables can contain number values. Some variables are used to store large or small numbers, and others are used for floating-point or fractional numbers. </paragraph> + </listitem> + <listitem> + <paragraph id="par_id3159226" role="listitem" xml-lang="en-US"> <emph>String</emph> variables contain character strings.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id3145217" role="listitem" xml-lang="en-US"> <emph>Boolean</emph> variables contain either the TRUE or the FALSE value.</paragraph> + </listitem> + <listitem> + <paragraph id="par_id3154762" role="listitem" xml-lang="en-US"> <emph>Object</emph> variables can store objects of various types, like tables and documents within a document.</paragraph> + </listitem></list> + +<h3 id="hd_id3153805">Integer Variables</h3> +<paragraph id="par_id3146966" role="paragraph" xml-lang="en-US">Integer variables range from -32768 to 32767. If you assign a floating-point value to an integer variable, the decimal places are rounded to the next integer. Integer variables are rapidly calculated in procedures and are suitable for counter variables in loops. An integer variable only requires two bytes of memory. "%" is the type-declaration character.</paragraph> +<bascode> +<paragraph id="par_idm1341159200" role="bascode" localize="false" xml-lang="en-US">Dim Variable%</paragraph> +<paragraph id="par_idm1341157968" role="bascode" localize="false" xml-lang="en-US">Dim Variable As Integer</paragraph> +</bascode> + +<h3 id="hd_id3147546">Long Integer Variables</h3> +<paragraph id="par_id3151193" role="paragraph" xml-lang="en-US">Long integer variables range from -2147483648 to 2147483647. If you assign a floating-point value to a long integer variable, the decimal places are rounded to the next integer. Long integer variables are rapidly calculated in procedures and are suitable for counter variables in loops for large values. A long integer variable requires four bytes of memory. "&" is the type-declaration character.</paragraph> +<bascode> +<paragraph id="par_idm1341151984" role="bascode" localize="false" xml-lang="en-US">Dim Variable&</paragraph> +<paragraph id="par_idm1341150736" role="bascode" localize="false" xml-lang="en-US">Dim Variable As Long</paragraph> +</bascode> + +<h3 id="hd_id7596972">Decimal Variables<comment>see i64349</comment></h3> +<paragraph id="par_id2649311" role="paragraph" xml-lang="en-US">Decimal variables can take positive or negative numbers or zero. Accuracy is up to 29 digits.</paragraph><comment>i85284</comment> +<paragraph id="par_id7617114" role="paragraph" xml-lang="en-US">You can use plus (+) or minus (-) signs as prefixes for decimal numbers (with or without spaces).</paragraph> +<paragraph id="par_id1593676" role="paragraph" xml-lang="en-US">If a decimal number is assigned to an integer variable, %PRODUCTNAME Basic rounds the figure up or down.<comment>information from "Programming Guide for BASIC" about decimal variables</comment></paragraph> + +<h3 id="hd_id3147500">Single Variables</h3> +<paragraph id="par_id3153070" role="paragraph" xml-lang="en-US">Single variables can take positive or negative values ranging from 3.402823 x 10E38 to 1.401298 x 10E-45. Single variables are floating-point variables, in which the decimal precision decreases as the non-decimal part of the number increases. Single variables are suitable for mathematical calculations of average precision. Calculations require more time than for Integer variables, but are faster than calculations with Double variables. A Single variable requires 4 bytes of memory. The type-declaration character is "!".</paragraph> +<bascode> +<paragraph id="par_idm1341137456" role="bascode" localize="false" xml-lang="en-US">Dim Variable!</paragraph> +<paragraph id="par_idm1341136224" role="bascode" localize="false" xml-lang="en-US">Dim Variable As Single</paragraph> +</bascode> + +<h3 id="hd_id3155753">Double Variables</h3> +<paragraph id="par_id3150953" role="paragraph" xml-lang="en-US">Double variables can take positive or negative values ranging from 1.79769313486232 x 10E308 to 4.94065645841247 x 10E-324. Double variables are floating-point variables, in which the decimal precision decreases as the non-decimal part of the number increases. Double variables are suitable for precise calculations. Calculations require more time than for Single variables. A Double variable requires 8 bytes of memory. The type-declaration character is "#".</paragraph> +<bascode> +<paragraph id="par_idm1341130144" role="bascode" xml-lang="en-US">Dim Variable#</paragraph> +<paragraph id="par_idm1341128912" role="bascode" localize="false" xml-lang="en-US">Dim Variable As Double</paragraph> +</bascode> + +<h3 id="hd_id3155747">Currency Variables</h3> +<paragraph id="par_id3153337" role="paragraph" xml-lang="en-US">Currency variables are internally stored as 64-bit numbers (8 Bytes) and displayed as a fixed-decimal number with 15 non-decimal and 4 decimal places. The values range from -922337203685477.5808 to +922337203685477.5807. Currency variables are used to calculate currency values with a high precision. The type-declaration character is "@".</paragraph> +<bascode> +<paragraph id="par_idm1341123216" role="bascode" localize="false" xml-lang="en-US">Dim Variable@</paragraph> +<paragraph id="par_idm1341121984" role="bascode" localize="false" xml-lang="en-US">Dim Variable As Currency</paragraph> +</bascode> + +<h3 id="hd_id301576839713868">Literals for integers</h3> +<paragraph role="paragraph" id="par_id1001576839723156">Numbers can be encoded using octal and hexadecimal forms.</paragraph> +<bascode> + <paragraph role="bascode" id="bas_id331576850637825" localize="false">xi = &o13 ' 8 + 3</paragraph> + <paragraph role="bascode" id="bas_id761576850640144" localize="false">ci = &h65 ' 6*16 + 5</paragraph> + <paragraph role="bascode" id="bas_id511576850640336" localize="false">MAX_Integer = &o77777 ' 32767 = &h7FFF</paragraph> + <paragraph role="bascode" id="bas_id571576850640536" localize="false">MIN_Integer = &o100000 ' -32768 = &h8000</paragraph> + <paragraph role="bascode" id="bas_id541576850641922" localize="false">MAX_Long = &h7fffffff ' 2147483647 = &o17777777777</paragraph> + <paragraph role="bascode" id="bas_id481576850564801" localize="false">MIN_Long = &h80000000 ' -2147483648 = &o20000000000</paragraph> +</bascode> + +<h3 id="hd_id3148742">String Variables</h3> +<paragraph id="par_id3151393" role="paragraph" xml-lang="en-US">String variables can hold character strings with up to 2,147,483,648 characters. Each character is stored as the corresponding Unicode value. String variables are suitable for word processing within programs and for temporary storage of any non-printable character up to a maximum length of 2 Gbytes. The memory required for storing string variables depends on the number of characters in the variable. The type-declaration character is "$".</paragraph> +<tip id="par_id381599081637549">In BASIC String functions, the first character of the string has index 1.</tip> +<bascode> +<paragraph id="par_idm1341116176" role="bascode" localize="false" xml-lang="en-US">Dim Variable$</paragraph> +<paragraph id="par_idm1341114944" role="bascode" localize="false" xml-lang="en-US">Dim Variable As String</paragraph> +</bascode> + +<h3 id="hd_id3150534">Boolean Variables</h3> +<paragraph id="par_id3145632" role="paragraph" xml-lang="en-US">Boolean variables store only one of two values: TRUE or FALSE. A number 0 evaluates to FALSE, every other value evaluates to TRUE.</paragraph> +<bascode> +<paragraph id="par_idm1341109456" role="bascode" localize="false" xml-lang="en-US">Dim Variable As Boolean</paragraph> +</bascode> + +<h3 id="hd_id3149722">Date Variables</h3> +<paragraph id="par_id3159116" role="paragraph" xml-lang="en-US">Date variables can only contain dates and time values stored in an internal format. Values assigned to Date variables with <link href="text/sbasic/shared/03030101.xhp" name="Dateserial"><emph>Dateserial</emph></link>, <link href="text/sbasic/shared/03030102.xhp" name="Datevalue"><emph>Datevalue</emph></link>, <link href="text/sbasic/shared/03030205.xhp" name="Timeserial"><emph>Timeserial</emph></link> or <link href="text/sbasic/shared/03030206.xhp" name="Timevalue"><emph>Timevalue</emph></link> are automatically converted to the internal format. Date-variables are converted to normal numbers by using the <link href="text/sbasic/shared/03030103.xhp" name="Day"><emph>Day</emph></link>, <link href="text/sbasic/shared/03030104.xhp" name="Month"><emph>Month</emph></link>, <link href="text/sbasic/shared/03030106.xhp" name="Year"><emph>Year</emph></link> or the <link href="text/sbasic/shared/03030201.xhp" name="Hour"><emph>Hour</emph></link>, <link href="text/sbasic/shared/03030202.xhp" name="Minute"><emph>Minute</emph></link>, <link href="text/sbasic/shared/03030204.xhp" name="Second"><emph>Second</emph></link> function. The internal format enables a comparison of date/time values by calculating the difference between two numbers. These variables can only be declared with the key word <emph>Date</emph>.</paragraph> +<bascode> +<paragraph id="par_idm1341092144" role="bascode" localize="false" xml-lang="en-US">Dim Variable As Date</paragraph> +</bascode> + +<bookmark xml-lang="en-US" branch="index" id="bm_id3150669"> + <bookmark_value>ampersand symbol; in literal notation</bookmark_value> + <bookmark_value>literals;hexadecimal</bookmark_value> + <bookmark_value>literals;octal</bookmark_value> + <bookmark_value>literals;&h notation</bookmark_value> + <bookmark_value>literals;&o notation</bookmark_value> +</bookmark> +<h3 id="hd_DateLiterals">Literals for Dates</h3> +<section id="DateLiterals"> +<paragraph role="paragraph" id="par_id151616083357363">Date literals allow to specify unambiguous date variables that are independent from the current language. Literals are enclosed between hash signs <literal>#</literal>. Possible formats are:</paragraph> +<list type="unordered"> + <listitem> + <paragraph id="par_id41616083766108" role="listitem" localize="false"><literal>#yyyy-mm-dd#</literal></paragraph> + </listitem> + <listitem> + <paragraph id="par_id271616083874773" role="listitem" localize="false"><literal>#mm/dd/yyyy#</literal></paragraph> + </listitem> +</list> +</section> +<bascode> + <paragraph role="bascode" id="bas_id201616314705492" localize="false">start_date = #12/30/1899# ' = 1</paragraph> + <paragraph role="bascode" id="bas_id616163714705267" localize="false">dob = #2010-09-28#</paragraph> +</bascode> + +<bookmark xml-lang="en-US" branch="index" id="bm_id601619552599885"> + <bookmark_value>The Variant type</bookmark_value> + <bookmark_value>The Any type</bookmark_value> +</bookmark> +<h2 id="VariantTypeH2">The Variant type</h2> +<paragraph role="paragraph" id="par_id1001619552129323">Variables declared as <emph>Variant</emph> can handle any data type. This means that the actual data type is defined during runtime as a value is assigned to the variable.</paragraph> +<paragraph role="paragraph" id="par_id631619552417188">There are three main ways to create a <emph>Variant</emph> variable, as shown below:</paragraph> +<bascode> + <paragraph role="bascode" id="bas_id751619554900163">Dim varA ' The type is not specified, hence the variable is a Variant</paragraph> + <paragraph role="bascode" id="bas_id181619554965451">Dim varB as Variant ' The variable is explicitly declared as a Variant</paragraph> + <paragraph role="bascode" id="bas_id371619554853094">varC = "abc" ' Previously undeclared variables are treated as Variants</paragraph> +</bascode> +<paragraph role="paragraph" id="par_id631619552417343">The example below uses the <link href="text/sbasic/shared/03103600.xhp" name="TypeName function">TypeName function</link> to show how the type of a <emph>Variant</emph> variable changes upon assignment.</paragraph> +<bascode> + <paragraph role="bascode" localize="false" id="bas_id221619552494450">Dim myVar As Variant</paragraph> + <paragraph role="bascode" localize="false" id="bas_id221619553194424">MsgBox TypeName(myVar) ' Empty</paragraph> + <paragraph role="bascode" localize="false" id="bas_id671619553194736">myVar = "Hello!"</paragraph> + <paragraph role="bascode" localize="false" id="bas_id91619553195040">MsgBox TypeName(myVar) ' String</paragraph> + <paragraph role="bascode" localize="false" id="bas_id731619553195384">myVar = 10</paragraph> + <paragraph role="bascode" localize="false" id="bas_id211619553195648">MsgBox TypeName(myVar) ' Integer</paragraph> +</bascode> +<note id="par_id141619553442668">A <emph>Variant</emph> variable is initialized with the <link href="text/sbasic/shared/03040000.xhp#objectconstants" name=" object constants">Empty</link> special data type. You can use the <link href="text/sbasic/shared/03102400.xhp" name="IsEmpty function">IsEmpty function</link> to test if a variable is an <emph>Empty Variant</emph>.</note> +<paragraph role="paragraph" id="par_id541619552755706">You can also use the keyword <emph>Any</emph> to declare a variable as a <emph>Variant</emph>. However, <emph>Any</emph> is deprecated and is available for backward compatibility.</paragraph> +<warning id="par_id711619622934043">Arguments with type <emph>Variant</emph> or <emph>Any</emph> passed in function calls are not checked for their types.</warning> +<bascode> + <paragraph role="bascode" id="bas_id141619552837486">Dim myVar As Any ' Variable "myVar" is a Variant</paragraph> +</bascode> + +<h2 id="hd_id3148732">Initial Variable Values</h2> +<paragraph id="par_id3154549" role="paragraph" xml-lang="en-US">As soon as the variable has been declared, it is automatically set to the "Null" value. Note the following conventions:</paragraph> +<paragraph id="par_id3143222" role="paragraph" xml-lang="en-US"> <emph>Numeric</emph> variables are automatically assigned the value "0" as soon as they are declared.</paragraph> +<paragraph id="par_id3150693" role="paragraph" xml-lang="en-US"> <emph>Date variables</emph> are assigned the value 0 internally; equivalent to converting the value to "0" with the <link href="text/sbasic/shared/03030103.xhp" name="Day"><emph>Day</emph></link>, <link href="text/sbasic/shared/03030104.xhp" name="Month"><emph>Month</emph></link>, <link href="text/sbasic/shared/03030106.xhp" name="Year"><emph>Year</emph></link> or the <link href="text/sbasic/shared/03030201.xhp" name="Hour"><emph>Hour</emph></link>, <link href="text/sbasic/shared/03030202.xhp" name="Minute"><emph>Minute</emph></link>, <link href="text/sbasic/shared/03030204.xhp" name="Second"><emph>Second</emph></link> function.</paragraph> +<paragraph id="par_id3154807" role="paragraph" xml-lang="en-US"> <emph>String variables</emph> are assigned an empty-string ("") when they are declared.</paragraph> + +<h2 id="hd_id3153936">Arrays</h2> +<paragraph id="par_id3148736" role="paragraph" xml-lang="en-US">$[officename] Basic knows one- or multi-dimensional arrays, defined by a specified variable type. Arrays are suitable for editing lists and tables in programs. Individual elements of an array can be addressed through a numeric index.</paragraph> +<paragraph id="par_id3149546" role="paragraph" xml-lang="en-US">Arrays <emph>must</emph> be declared with the <emph>Dim</emph> statement. There are several ways to define the index range of an array:</paragraph> + +<bascode> + <paragraph id="par_idm1341065280" role="bascode">Dim Text$(20) '21 elements numbered from 0 to 20'</paragraph> + <paragraph id="par_idm1341059776" role="bascode">Dim Text$(5,4) '30 elements (a matrix of 6 x 5 elements)'</paragraph> + <paragraph id="par_idm1341054256" role="bascode">Dim Text$(5 To 25) '21 elements numbered from 5 to 25'</paragraph> + <paragraph id="par_idm1341048752" role="bascode">Dim Text$(-15 To 5) '21 elements (including 0), numbered from -15 to 5'</paragraph> +</bascode> + +<paragraph id="par_id3153005" role="paragraph" xml-lang="en-US">The index range can include positive as well as negative numbers. <comment>i36558</comment></paragraph> + +<h2 id="hd_id3154507">Constants</h2> +<paragraph id="par_id3156357" role="paragraph" xml-lang="en-US">Constants have a fixed value. They are only defined once in the program and cannot be redefined later:</paragraph> +<bascode> +<paragraph id="par_idm1341038256" role="bascode" localize="false" xml-lang="en-US">Const ConstName=Expression</paragraph> +</bascode> + <section id="relatedtopics"> + <paragraph role="paragraph" id="par_id281619620439154" localize="false"><embedvar href="text/sbasic/shared/03040000.xhp#basicconstantsh1" markup="ignore"/></paragraph> + <paragraph role="paragraph" id="par_id641619620637722" localize="false"><embedvar href="text/sbasic/shared/03102100.xhp#Dimh1" markup="ignore"/></paragraph> +</section> +</body> +</helpdocument> |