From 2d429e75ce69e77f8c95490ac03881ec9aa0354a Mon Sep 17 00:00:00 2001
From: Marti Bolivar <mbolivar@mit.edu>
Date: Mon, 25 Oct 2010 21:15:28 -0400
Subject: arduino language reference nearing completion, properly CC-BY-SA 3.0
 attributed

---
 source/arduino/long.rst | 62 +++++++++++++++++++++++++------------------------
 1 file changed, 32 insertions(+), 30 deletions(-)

(limited to 'source/arduino/long.rst')

diff --git a/source/arduino/long.rst b/source/arduino/long.rst
index 3d59896..6d20111 100644
--- a/source/arduino/long.rst
+++ b/source/arduino/long.rst
@@ -1,3 +1,5 @@
+.. highlight:: cpp
+
 .. _arduino-long:
 
 long
@@ -6,45 +8,45 @@ long
 Description
 -----------
 
-Long variables are extended size variables for number storage, and
-store 32 bits (4 bytes), from -2,147,483,648 to 2,147,483,647.
-
-
-
-Example
--------
-
-
-
-::
+The ``long`` data type stores extended size integer values.  You can
+use a ``long`` when your values are too large to fit into an :ref:`int
+<arduino-int>`.  A ``long`` occupies 8 bytes of memory.  This yields a
+range of approximately -9.2×10^18 to 9.2×10^18 (that's 9.2 billion
+billion, or about 92 million times the number of stars in the Milky
+Way galaxy).  The exact range of a ``long`` on the Maple is from
+-9,223,372,036,854,775,808 to 9,223,372,036,854,775,807, or -2^63 to
+(2^63-1).
 
-        long speedOfLight = 186000L;   // see Integer Constants for explanation of the 'L'
+Here's an example of declaring a long (see :ref:`integer constants
+<arduino-constants-u-l>` for explanation of the 'L')::
 
+        // Speed of light in nanometers per second (approximate).
+        long c = 299792458000000000L;
 
+The general syntax for declaring an ``long`` variable named ``var``,
+then giving it value ``val``, looks like::
 
-Syntax
-------
+    long var = val;
 
-::
-
-        long var = val;
-
-
-
-
--  var - the long variable name
--  val - the value assigned to the variable
+This is identical to the ``int`` syntax, with ``long`` replacing
+``int``.
 
+Note that ``long`` values will still :ref:`overflow
+<arduino-int-overflow>`, just like ``int`` values, but their much
+larger range makes this less likely to happen.
 
+The downside to using a ``long`` instead of an ``int`` (besides the
+extra storage) is that :ref:`arithmetic <arduino-arithmetic>`
+operations on ``long``\ s will take longer than on ``int``\ s.
 
 See Also
 --------
 
-
--  `byte <http://arduino.cc/en/Reference/Byte>`_
--  `int <http://arduino.cc/en/Reference/Int>`_
--  `unsigned int <http://arduino.cc/en/Reference/UnsignedInt>`_
--  `unsigned long <http://arduino.cc/en/Reference/UnsignedLong>`_
--  `Integer Constants <http://arduino.cc/en/Reference/IntegerConstants>`_
--  `Variable Declaration <http://arduino.cc/en/Reference/VariableDeclaration>`_
+-  :ref:`char <arduino-char>`
+-  :ref:`unsigned char <arduino-unsignedchar>`
+-  :ref:`int <arduino-int>`
+-  :ref:`unsigned int <arduino-unsignedint>`
+-  :ref:`unsigned long <arduino-unsignedlong>`
+-  :ref:`Integer Constants <arduino-constants-integers>`
+-  :ref:`Variables <arduino-variables>`
 
-- 
cgit v1.2.3