<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Base.Cartesian — Julia Language 0.3.4 documentation</title>
<link href='https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="../_static/julia.css" type="text/css" />
<link rel="stylesheet" href="../_static/julia.css" type="text/css" />
<link rel="top" title="Julia Language 0.3.4 documentation" href="../index.html"/>
<link rel="up" title="Documentation of Julia’s Internals" href="julia.html"/>
<link rel="next" title="System Image Building" href="sysimg.html"/>
<link rel="prev" title="Documentation of Julia’s Internals" href="julia.html"/>
<script src="https://cdnjs.cloudflare.com/ajax/libs/modernizr/2.6.2/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="http://julialang.org/"><img src="../_static/julia-logo.svg" class="logo"></a>
<!--
<a href="../index.html" class="fa fa-home"> Julia Language</a>
-->
<div role="search">
<form id ="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../manual/introduction.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../manual/getting-started.html">Getting Started</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/getting-started.html#resources">Resources</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/variables.html">Variables</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/variables.html#allowed-variable-names">Allowed Variable Names</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/variables.html#stylistic-conventions">Stylistic Conventions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/integers-and-floating-point-numbers.html">Integers and Floating-Point Numbers</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/integers-and-floating-point-numbers.html#integers">Integers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/integers-and-floating-point-numbers.html#floating-point-numbers">Floating-Point Numbers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/integers-and-floating-point-numbers.html#arbitrary-precision-arithmetic">Arbitrary Precision Arithmetic</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/integers-and-floating-point-numbers.html#numeric-literal-coefficients">Numeric Literal Coefficients</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/integers-and-floating-point-numbers.html#literal-zero-and-one">Literal zero and one</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/mathematical-operations.html">Mathematical Operations and Elementary Functions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/mathematical-operations.html#arithmetic-operators">Arithmetic Operators</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/mathematical-operations.html#bitwise-operators">Bitwise Operators</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/mathematical-operations.html#updating-operators">Updating operators</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/mathematical-operations.html#numeric-comparisons">Numeric Comparisons</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/mathematical-operations.html#elementary-functions">Elementary Functions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/complex-and-rational-numbers.html">Complex and Rational Numbers</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/complex-and-rational-numbers.html#complex-numbers">Complex Numbers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/complex-and-rational-numbers.html#rational-numbers">Rational Numbers</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/strings.html">Strings</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/strings.html#characters">Characters</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/strings.html#string-basics">String Basics</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/strings.html#unicode-and-utf-8">Unicode and UTF-8</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/strings.html#interpolation">Interpolation</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/strings.html#common-operations">Common Operations</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/strings.html#non-standard-string-literals">Non-Standard String Literals</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/strings.html#regular-expressions">Regular Expressions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/strings.html#id3">Byte Array Literals</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/strings.html#version-number-literals">Version Number Literals</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/functions.html">Functions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/functions.html#argument-passing-behavior">Argument Passing Behavior</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/functions.html#the-return-keyword">The <tt class="docutils literal"><span class="pre">return</span></tt> Keyword</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/functions.html#id1">Operators Are Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/functions.html#operators-with-special-names">Operators With Special Names</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/functions.html#anonymous-functions">Anonymous Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/functions.html#multiple-return-values">Multiple Return Values</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/functions.html#varargs-functions">Varargs Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/functions.html#optional-arguments">Optional Arguments</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/functions.html#keyword-arguments">Keyword Arguments</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/functions.html#evaluation-scope-of-default-values">Evaluation Scope of Default Values</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/functions.html#block-syntax-for-function-arguments">Block Syntax for Function Arguments</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/functions.html#further-reading">Further Reading</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/control-flow.html">Control Flow</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/control-flow.html#compound-expressions">Compound Expressions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/control-flow.html#conditional-evaluation">Conditional Evaluation</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/control-flow.html#short-circuit-evaluation">Short-Circuit Evaluation</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/control-flow.html#repeated-evaluation-loops">Repeated Evaluation: Loops</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/control-flow.html#exception-handling">Exception Handling</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/control-flow.html#tasks-aka-coroutines">Tasks (aka Coroutines)</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/variables-and-scoping.html">Scope of Variables</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/variables-and-scoping.html#for-loops-and-comprehensions">For Loops and Comprehensions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/variables-and-scoping.html#constants">Constants</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/types.html">Types</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/types.html#type-declarations">Type Declarations</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/types.html#abstract-types">Abstract Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/types.html#bits-types">Bits Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/types.html#composite-types">Composite Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/types.html#immutable-composite-types">Immutable Composite Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/types.html#declared-types">Declared Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/types.html#tuple-types">Tuple Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/types.html#type-unions">Type Unions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/types.html#man-parametric-types">Parametric Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/types.html#type-aliases">Type Aliases</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/types.html#operations-on-types">Operations on Types</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/methods.html">Methods</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/methods.html#defining-methods">Defining Methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/methods.html#method-ambiguities">Method Ambiguities</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/methods.html#parametric-methods">Parametric Methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/methods.html#note-on-optional-and-keyword-arguments">Note on Optional and keyword Arguments</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/constructors.html">Constructors</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/constructors.html#outer-constructor-methods">Outer Constructor Methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/constructors.html#inner-constructor-methods">Inner Constructor Methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/constructors.html#incomplete-initialization">Incomplete Initialization</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/constructors.html#parametric-constructors">Parametric Constructors</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/constructors.html#case-study-rational">Case Study: Rational</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/conversion-and-promotion.html">Conversion and Promotion</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/conversion-and-promotion.html#conversion">Conversion</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/conversion-and-promotion.html#promotion">Promotion</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/modules.html">Modules</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/modules.html#summary-of-module-usage">Summary of module usage</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/metaprogramming.html">Metaprogramming</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/metaprogramming.html#expressions-and-eval">Expressions and Eval</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/metaprogramming.html#macros">Macros</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/metaprogramming.html#reflection">Reflection</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/arrays.html">Multi-dimensional Arrays</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/arrays.html#arrays">Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/arrays.html#sparse-matrices">Sparse Matrices</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/linear-algebra.html">Linear algebra</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/linear-algebra.html#matrix-factorizations">Matrix factorizations</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/linear-algebra.html#special-matrices">Special matrices</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/networking-and-streams.html">Networking and Streams</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/networking-and-streams.html#basic-stream-i-o">Basic Stream I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/networking-and-streams.html#text-i-o">Text I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/networking-and-streams.html#working-with-files">Working with Files</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/networking-and-streams.html#a-simple-tcp-example">A simple TCP example</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/networking-and-streams.html#resolving-ip-addresses">Resolving IP Addresses</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/parallel-computing.html">Parallel Computing</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/parallel-computing.html#data-movement">Data Movement</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/parallel-computing.html#parallel-map-and-loops">Parallel Map and Loops</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/parallel-computing.html#synchronization-with-remote-references">Synchronization With Remote References</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/parallel-computing.html#scheduling">Scheduling</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/parallel-computing.html#distributed-arrays">Distributed Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/parallel-computing.html#constructing-distributed-arrays">Constructing Distributed Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/parallel-computing.html#distributed-array-operations">Distributed Array Operations</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/parallel-computing.html#shared-arrays-experimental">Shared Arrays (Experimental)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/parallel-computing.html#clustermanagers">ClusterManagers</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/running-external-programs.html">Running External Programs</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/running-external-programs.html#interpolation">Interpolation</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/running-external-programs.html#quoting">Quoting</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/running-external-programs.html#pipelines">Pipelines</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/calling-c-and-fortran-code.html">Calling C and Fortran Code</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/calling-c-and-fortran-code.html#mapping-c-types-to-julia">Mapping C Types to Julia</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/calling-c-and-fortran-code.html#accessing-data-through-a-pointer">Accessing Data through a Pointer</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/calling-c-and-fortran-code.html#passing-pointers-for-modifying-inputs">Passing Pointers for Modifying Inputs</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/calling-c-and-fortran-code.html#garbage-collection-safety">Garbage Collection Safety</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/calling-c-and-fortran-code.html#non-constant-function-specifications">Non-constant Function Specifications</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/calling-c-and-fortran-code.html#indirect-calls">Indirect Calls</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/calling-c-and-fortran-code.html#calling-convention">Calling Convention</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/calling-c-and-fortran-code.html#accessing-global-variables">Accessing Global Variables</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/calling-c-and-fortran-code.html#passing-julia-callback-functions-to-c">Passing Julia Callback Functions to C</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/calling-c-and-fortran-code.html#c">C++</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/calling-c-and-fortran-code.html#handling-platform-variations">Handling Platform Variations</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/interacting-with-julia.html">Interacting With Julia</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/interacting-with-julia.html#the-different-prompt-modes">The different prompt modes</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/interacting-with-julia.html#key-bindings">Key bindings</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/embedding.html">Embedding Julia</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/embedding.html#high-level-embedding">High-Level Embedding</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/embedding.html#converting-types">Converting Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/embedding.html#calling-julia-functions">Calling Julia Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/embedding.html#memory-management">Memory Management</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/embedding.html#working-with-arrays">Working with Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/embedding.html#exceptions">Exceptions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/packages.html">Packages</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/packages.html#package-status">Package Status</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/packages.html#adding-and-removing-packages">Adding and Removing Packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/packages.html#installing-unregistered-packages">Installing Unregistered Packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/packages.html#updating-packages">Updating Packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/packages.html#checkout-pin-and-free">Checkout, Pin and Free</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/packages.html#package-development">Package Development</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/packages.html#initial-setup">Initial Setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/packages.html#generating-a-new-package">Generating a New Package</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/packages.html#making-your-package-available">Making Your Package Available</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/packages.html#publishing-your-package">Publishing Your Package</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/packages.html#tagging-package-versions">Tagging Package Versions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/packages.html#fixing-package-requirements">Fixing Package Requirements</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/packages.html#man-package-requirements">Requirements Specification</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/performance-tips.html">Performance Tips</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/performance-tips.html#avoid-global-variables">Avoid global variables</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/performance-tips.html#measure-performance-with-time-and-pay-attention-to-memory-allocation">Measure performance with <tt class="docutils literal"><span class="pre">@time</span></tt> and pay attention to memory allocation</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/performance-tips.html#tools">Tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/performance-tips.html#avoid-containers-with-abstract-type-parameters">Avoid containers with abstract type parameters</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/performance-tips.html#type-declarations">Type declarations</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/performance-tips.html#break-functions-into-multiple-definitions">Break functions into multiple definitions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/performance-tips.html#write-type-stable-functions">Write “type-stable” functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/performance-tips.html#avoid-changing-the-type-of-a-variable">Avoid changing the type of a variable</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/performance-tips.html#separate-kernel-functions">Separate kernel functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/performance-tips.html#access-arrays-in-memory-order-along-columns">Access arrays in memory order, along columns</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/performance-tips.html#pre-allocating-outputs">Pre-allocating outputs</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/performance-tips.html#avoid-string-interpolation-for-i-o">Avoid string interpolation for I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/performance-tips.html#fix-deprecation-warnings">Fix deprecation warnings</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/performance-tips.html#tweaks">Tweaks</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/performance-tips.html#performance-annotations">Performance Annotations</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/style-guide.html">Style Guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/style-guide.html#write-functions-not-just-scripts">Write functions, not just scripts</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/style-guide.html#avoid-writing-overly-specific-types">Avoid writing overly-specific types</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/style-guide.html#handle-excess-argument-diversity-in-the-caller">Handle excess argument diversity in the caller</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/style-guide.html#append-to-names-of-functions-that-modify-their-arguments">Append <cite>!</cite> to names of functions that modify their arguments</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/style-guide.html#avoid-strange-type-unions">Avoid strange type Unions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/style-guide.html#try-to-avoid-nullable-fields">Try to avoid nullable fields</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/style-guide.html#avoid-elaborate-container-types">Avoid elaborate container types</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/style-guide.html#avoid-underscores-in-names">Avoid underscores in names</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/style-guide.html#don-t-overuse-try-catch">Don’t overuse try-catch</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/style-guide.html#don-t-parenthesize-conditions">Don’t parenthesize conditions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/style-guide.html#don-t-overuse">Don’t overuse ...</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/style-guide.html#don-t-use-unnecessary-static-parameters">Don’t use unnecessary static parameters</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/style-guide.html#avoid-confusion-about-whether-something-is-an-instance-or-a-type">Avoid confusion about whether something is an instance or a type</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/style-guide.html#don-t-overuse-macros">Don’t overuse macros</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/style-guide.html#don-t-expose-unsafe-operations-at-the-interface-level">Don’t expose unsafe operations at the interface level</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/style-guide.html#don-t-overload-methods-of-base-container-types">Don’t overload methods of base container types</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/style-guide.html#be-careful-with-type-equality">Be careful with type equality</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/style-guide.html#do-not-write-x-f-x">Do not write <tt class="docutils literal"><span class="pre">x->f(x)</span></tt></a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/faq.html">Frequently Asked Questions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/faq.html#sessions-and-the-repl">Sessions and the REPL</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/faq.html#functions">Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/faq.html#types-type-declarations-and-constructors">Types, type declarations, and constructors</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/faq.html#nothingness-and-missing-values">Nothingness and missing values</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/faq.html#julia-releases">Julia Releases</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/faq.html#developing-julia">Developing Julia</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../manual/noteworthy-differences.html">Noteworthy Differences from other Languages</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../manual/noteworthy-differences.html#noteworthy-differences-from-matlab">Noteworthy differences from MATLAB</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/noteworthy-differences.html#noteworthy-differences-from-r">Noteworthy differences from R</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manual/noteworthy-differences.html#noteworthy-differences-from-python">Noteworthy differences from Python</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/base.html">The Standard Library</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#introduction">Introduction</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#getting-around">Getting Around</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#all-objects">All Objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#types">Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#generic-functions">Generic Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#syntax">Syntax</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#iteration">Iteration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#general-collections">General Collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#iterable-collections">Iterable Collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#indexable-collections">Indexable Collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#associative-collections">Associative Collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#set-like-collections">Set-Like Collections</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#dequeues">Dequeues</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#strings">Strings</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#i-o">I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#network-i-o">Network I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#text-i-o">Text I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#multimedia-i-o">Multimedia I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#memory-mapped-i-o">Memory-mapped I/O</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#standard-numeric-types">Standard Numeric Types</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#mathematical-operators">Mathematical Operators</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#mathematical-functions">Mathematical Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#data-formats">Data Formats</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#numbers">Numbers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#bigfloats">BigFloats</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#random-numbers">Random Numbers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#arrays">Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#combinatorics">Combinatorics</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#statistics">Statistics</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#signal-processing">Signal Processing</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#numerical-integration">Numerical Integration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#parallel-computing">Parallel Computing</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#distributed-arrays">Distributed Arrays</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#shared-arrays-experimental-unix-only-feature">Shared Arrays (Experimental, UNIX-only feature)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#system">System</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#c-interface">C Interface</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#errors">Errors</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#tasks">Tasks</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#events">Events</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#reflection">Reflection</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/base.html#internals">Internals</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/sparse.html">Sparse Matrices</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/linalg.html">Linear Algebra</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/linalg.html#module-Base.LinAlg.BLAS">BLAS Functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/constants.html">Constants</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/file.html">Filesystem</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/punctuation.html">Punctuation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/sort.html">Sorting and Related Functions</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/sort.html#sorting-functions">Sorting Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/sort.html#order-related-functions">Order-Related Functions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/sort.html#sorting-algorithms">Sorting Algorithms</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/pkg.html">Package Manager Functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/collections.html">Collections and Data Structures</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/collections.html#priorityqueue">PriorityQueue</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/collections.html#heap-functions">Heap Functions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/graphics.html">Graphics</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/graphics.html#geometry">Geometry</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/test.html">Unit and Functional Testing</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/test.html#overview">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/test.html#handlers">Handlers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/test.html#macros">Macros</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/test.html#functions">Functions</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/test.html#testing-base-julia">Testing Base Julia</a></li>
<li class="toctree-l1"><a class="reference internal" href="../stdlib/profile.html">Profiling</a><ul>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/profile.html#basic-usage">Basic usage</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/profile.html#accumulation-and-clearing">Accumulation and clearing</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/profile.html#options-for-controlling-the-display-of-profile-results">Options for controlling the display of profile results</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/profile.html#configuration">Configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="../stdlib/profile.html#function-reference">Function reference</a></li>
</ul>
</li>
</ul>
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="julia.html">Documentation of Julia’s Internals</a><ul class="current">
<li class="toctree-l2 current"><a class="current reference internal" href="">Base.Cartesian</a></li>
<li class="toctree-l2"><a class="reference internal" href="sysimg.html">System Image Building</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="C.html">Developing/debugging Julia’s C code</a><ul>
<li class="toctree-l2"><a class="reference internal" href="backtraces.html">Reporting and analyzing crashes (segfaults)</a></li>
<li class="toctree-l2"><a class="reference internal" href="debuggingtips.html">gdb debugging tips</a></li>
</ul>
</li>
</ul>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">Julia Language</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html">Docs</a> »</li>
<li><a href="julia.html">Documentation of Julia’s Internals</a> »</li>
<li>Base.Cartesian</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/devdocs/cartesian.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document">
<span class="target" id="module-Base.Cartesian"></span><div class="section" id="base-cartesian">
<span id="devdocs-cartesian"></span><h1>Base.Cartesian<a class="headerlink" href="#base-cartesian" title="Permalink to this headline">¶</a></h1>
<p>The (non-exported) Cartesian module provides macros that facilitate
writing multidimensional algorithms. It is hoped that Cartesian will
not, in the long term, be necessary; however, at present it is one of
the few ways to write compact and performant multidimensional code.</p>
<div class="section" id="principles-of-usage">
<h2>Principles of usage<a class="headerlink" href="#principles-of-usage" title="Permalink to this headline">¶</a></h2>
<p>A simple example of usage is:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="p">@</span><span class="n">nloops</span> <span class="mi">3</span> <span class="n">i</span> <span class="n">A</span> <span class="k">begin</span>
<span class="n">s</span> <span class="o">+=</span> <span class="p">@</span><span class="n">nref</span> <span class="mi">3</span> <span class="n">A</span> <span class="n">i</span>
<span class="k">end</span>
</pre></div>
</div>
<p>which generates the following code:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="k">for</span> <span class="n">i_3</span> <span class="o">=</span> <span class="mi">1</span><span class="p">:</span><span class="n">size</span><span class="p">(</span><span class="n">A</span><span class="p">,</span><span class="mi">3</span><span class="p">)</span>
<span class="k">for</span> <span class="n">i_2</span> <span class="o">=</span> <span class="mi">1</span><span class="p">:</span><span class="n">size</span><span class="p">(</span><span class="n">A</span><span class="p">,</span><span class="mi">2</span><span class="p">)</span>
<span class="k">for</span> <span class="n">i_1</span> <span class="o">=</span> <span class="mi">1</span><span class="p">:</span><span class="n">size</span><span class="p">(</span><span class="n">A</span><span class="p">,</span><span class="mi">1</span><span class="p">)</span>
<span class="n">s</span> <span class="o">+=</span> <span class="n">A</span><span class="p">[</span><span class="n">i_1</span><span class="p">,</span><span class="n">i_2</span><span class="p">,</span><span class="n">i_3</span><span class="p">]</span>
<span class="k">end</span>
<span class="k">end</span>
<span class="k">end</span>
</pre></div>
</div>
<p>In general, Cartesian allows you to write generic code that contains
repetitive elements, like the nested loops in this example. Other
applications include repeated expressions (e.g., loop unwinding) or
creating function calls with variable numbers of arguments without using
the “splat” construct (<tt class="docutils literal"><span class="pre">i...</span></tt>).</p>
</div>
<div class="section" id="basic-syntax">
<h2>Basic syntax<a class="headerlink" href="#basic-syntax" title="Permalink to this headline">¶</a></h2>
<p>The (basic) syntax of <tt class="docutils literal"><span class="pre">@nloops</span></tt> is as follows:</p>
<ul class="simple">
<li>The first argument must be an integer (<em>not</em> a variable) specifying
the number of loops.</li>
<li>The second argument is the symbol-prefix used for the iterator
variable. Here we used <tt class="docutils literal"><span class="pre">i</span></tt>, and variables <tt class="docutils literal"><span class="pre">i_1,</span> <span class="pre">i_2,</span> <span class="pre">i_3</span></tt> were
generated.</li>
<li>The third argument specifies the range for each iterator variable. If
you use a variable (symbol) here, it’s taken as <tt class="docutils literal"><span class="pre">1:size(A,dim)</span></tt>.
More flexibly, you can use the anonymous-function expression syntax
described below.</li>
<li>The last argument is the body of the loop. Here, that’s what appears
between the <tt class="docutils literal"><span class="pre">begin...end</span></tt>.</li>
</ul>
<p>There are some additional features of <tt class="docutils literal"><span class="pre">@nloops</span></tt> described in the
<a class="reference internal" href="#devdoc-cartesian-reference"><em>reference section</em></a>.</p>
<p><tt class="docutils literal"><span class="pre">@nref</span></tt> follows a similar pattern, generating <tt class="docutils literal"><span class="pre">A[i_1,i_2,i_3]</span></tt> from
<tt class="docutils literal"><span class="pre">@nref</span> <span class="pre">3</span> <span class="pre">A</span> <span class="pre">i</span></tt>. The general practice is to read from left to right,
which is why <tt class="docutils literal"><span class="pre">@nloops</span></tt> is <tt class="docutils literal"><span class="pre">@nloops</span> <span class="pre">3</span> <span class="pre">i</span> <span class="pre">A</span> <span class="pre">expr</span></tt> (as in
<tt class="docutils literal"><span class="pre">for</span> <span class="pre">i_2</span> <span class="pre">=</span> <span class="pre">1:size(A,2)</span></tt>, where <tt class="docutils literal"><span class="pre">i_2</span></tt> is to the left and the range is
to the right) whereas <tt class="docutils literal"><span class="pre">@nref</span></tt> is <tt class="docutils literal"><span class="pre">@nref</span> <span class="pre">3</span> <span class="pre">A</span> <span class="pre">i</span></tt> (as in
<tt class="docutils literal"><span class="pre">A[i_1,i_2,i_3]</span></tt>, where the array comes first).</p>
<p>If you’re developing code with Cartesian, you may find that debugging is
easier when you examine the generated code, using <tt class="docutils literal"><span class="pre">macroexpand</span></tt>:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="n">macroexpand</span><span class="p">(:(@</span><span class="n">nref</span> <span class="mi">2</span> <span class="n">A</span> <span class="n">i</span><span class="p">))</span>
<span class="p">:(</span><span class="n">A</span><span class="p">[</span><span class="n">i_1</span><span class="p">,</span><span class="n">i_2</span><span class="p">])</span>
</pre></div>
</div>
<div class="section" id="supplying-the-number-of-expressions">
<h3>Supplying the number of expressions<a class="headerlink" href="#supplying-the-number-of-expressions" title="Permalink to this headline">¶</a></h3>
<p>The first argument to both of these macros is the number of
expressions, which must be an integer. When you’re writing a function
that you intend to work in multiple dimensions, this may not be
something you want to hard-code. Perhaps the most straightforward
approach is to use the <tt class="docutils literal"><span class="pre">@ngenerate</span></tt> macro.</p>
<p>Perhaps the easiest way to understand <tt class="docutils literal"><span class="pre">@ngenerate</span></tt> is to see it in
action. Here’s a slightly cleaned up example:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">julia</span><span class="o">></span> <span class="n">macroexpand</span><span class="p">(:(@</span><span class="n">ngenerate</span> <span class="n">N</span> <span class="nb">typeof</span><span class="p">(</span><span class="n">A</span><span class="p">)</span> <span class="k">function</span><span class="nf"> mysum</span><span class="p">{</span><span class="n">T</span><span class="p">,</span><span class="n">N</span><span class="p">}(</span><span class="n">A</span><span class="p">::</span><span class="n">Array</span><span class="p">{</span><span class="n">T</span><span class="p">,</span><span class="n">N</span><span class="p">})</span>
<span class="n">s</span> <span class="o">=</span> <span class="n">zero</span><span class="p">(</span><span class="n">T</span><span class="p">)</span>
<span class="p">@</span><span class="n">nloops</span> <span class="n">N</span> <span class="n">i</span> <span class="n">A</span> <span class="k">begin</span>
<span class="n">s</span> <span class="o">+=</span> <span class="p">@</span><span class="n">nref</span> <span class="n">N</span> <span class="n">A</span> <span class="n">i</span>
<span class="k">end</span>
<span class="n">s</span>
<span class="k">end</span><span class="p">))</span>
<span class="p">:(</span><span class="k">begin</span>
<span class="k">function</span><span class="nf"> mysum</span><span class="p">{</span><span class="n">T</span><span class="p">}(</span><span class="n">A</span><span class="p">::</span><span class="n">Array</span><span class="p">{</span><span class="n">T</span><span class="p">,</span><span class="mi">1</span><span class="p">})</span> <span class="c"># none, line 2:</span>
<span class="n">s</span> <span class="o">=</span> <span class="n">zero</span><span class="p">(</span><span class="n">T</span><span class="p">)</span> <span class="c"># line 3:</span>
<span class="k">for</span> <span class="n">i_1</span> <span class="o">=</span> <span class="mi">1</span><span class="p">:</span><span class="n">size</span><span class="p">(</span><span class="n">A</span><span class="p">,</span><span class="mi">1</span><span class="p">)</span> <span class="c"># line 293:</span>
<span class="n">s</span> <span class="o">+=</span> <span class="n">A</span><span class="p">[</span><span class="n">i_1</span><span class="p">]</span>
<span class="k">end</span> <span class="c"># line 295:</span>
<span class="n">s</span>
<span class="k">end</span>
<span class="k">function</span><span class="nf"> mysum</span><span class="p">{</span><span class="n">T</span><span class="p">}(</span><span class="n">A</span><span class="p">::</span><span class="n">Array</span><span class="p">{</span><span class="n">T</span><span class="p">,</span><span class="mi">2</span><span class="p">})</span> <span class="c"># none, line 2:</span>
<span class="n">s</span> <span class="o">=</span> <span class="n">zero</span><span class="p">(</span><span class="n">T</span><span class="p">)</span> <span class="c"># line 3:</span>
<span class="k">for</span> <span class="n">i_2</span> <span class="o">=</span> <span class="mi">1</span><span class="p">:</span><span class="n">size</span><span class="p">(</span><span class="n">A</span><span class="p">,</span><span class="mi">2</span><span class="p">)</span> <span class="c"># line 293:</span>
<span class="k">for</span> <span class="n">i_1</span> <span class="o">=</span> <span class="mi">1</span><span class="p">:</span><span class="n">size</span><span class="p">(</span><span class="n">A</span><span class="p">,</span><span class="mi">1</span><span class="p">)</span> <span class="c"># line 293:</span>
<span class="n">s</span> <span class="o">+=</span> <span class="n">A</span><span class="p">[</span><span class="n">i_1</span><span class="p">,</span><span class="n">i_2</span><span class="p">]</span>
<span class="k">end</span> <span class="c"># line 295:</span>
<span class="k">end</span> <span class="c"># line 295:</span>
<span class="n">s</span>
<span class="k">end</span>
<span class="k">function</span><span class="nf"> mysum</span><span class="p">{</span><span class="n">T</span><span class="p">}(</span><span class="n">A</span><span class="p">::</span><span class="n">Array</span><span class="p">{</span><span class="n">T</span><span class="p">,</span><span class="mi">3</span><span class="p">})</span> <span class="c"># none, line 2:</span>
<span class="n">s</span> <span class="o">=</span> <span class="n">zero</span><span class="p">(</span><span class="n">T</span><span class="p">)</span> <span class="c"># line 3:</span>
<span class="k">for</span> <span class="n">i_3</span> <span class="o">=</span> <span class="mi">1</span><span class="p">:</span><span class="n">size</span><span class="p">(</span><span class="n">A</span><span class="p">,</span><span class="mi">3</span><span class="p">)</span> <span class="c"># line 293:</span>
<span class="k">for</span> <span class="n">i_2</span> <span class="o">=</span> <span class="mi">1</span><span class="p">:</span><span class="n">size</span><span class="p">(</span><span class="n">A</span><span class="p">,</span><span class="mi">2</span><span class="p">)</span> <span class="c"># line 293:</span>
<span class="k">for</span> <span class="n">i_1</span> <span class="o">=</span> <span class="mi">1</span><span class="p">:</span><span class="n">size</span><span class="p">(</span><span class="n">A</span><span class="p">,</span><span class="mi">1</span><span class="p">)</span> <span class="c"># line 293:</span>
<span class="n">s</span> <span class="o">+=</span> <span class="n">A</span><span class="p">[</span><span class="n">i_1</span><span class="p">,</span><span class="n">i_2</span><span class="p">,</span><span class="n">i_3</span><span class="p">]</span>
<span class="k">end</span> <span class="c"># line 295:</span>
<span class="k">end</span> <span class="c"># line 295:</span>
<span class="k">end</span> <span class="c"># line 295:</span>
<span class="n">s</span>
<span class="k">end</span>
<span class="k">function</span><span class="nf"> mysum</span><span class="p">{</span><span class="n">T</span><span class="p">}(</span><span class="n">A</span><span class="p">::</span><span class="n">Array</span><span class="p">{</span><span class="n">T</span><span class="p">,</span><span class="mi">4</span><span class="p">})</span> <span class="c"># none, line 2:</span>
<span class="o">...</span>
<span class="k">end</span>
<span class="k">let</span> <span class="n">mysum_cache</span> <span class="o">=</span> <span class="n">Dict</span><span class="p">{</span><span class="kt">Int</span><span class="p">,</span><span class="n">Function</span><span class="p">}()</span> <span class="c"># line 113:</span>
<span class="k">function</span><span class="nf"> mysum</span><span class="p">{</span><span class="n">T</span><span class="p">,</span><span class="n">N</span><span class="p">}(</span><span class="n">A</span><span class="p">::</span><span class="n">Array</span><span class="p">{</span><span class="n">T</span><span class="p">,</span><span class="n">N</span><span class="p">})</span> <span class="c"># cartesian.jl, line 100:</span>
<span class="k">if</span> <span class="o">!</span><span class="p">(</span><span class="n">haskey</span><span class="p">(</span><span class="n">mysum_cache</span><span class="p">,</span><span class="n">N</span><span class="p">))</span> <span class="c"># line 102:</span>
<span class="n">localfunc</span> <span class="o">=</span> <span class="k">quote</span>
<span class="k">function</span><span class="nf"> _F_</span><span class="p">{</span><span class="n">T</span><span class="p">}(</span><span class="n">A</span><span class="p">::</span><span class="n">Array</span><span class="p">{</span><span class="n">T</span><span class="p">,</span><span class="o">$</span><span class="n">N</span><span class="p">})</span>
<span class="n">s</span> <span class="o">=</span> <span class="n">zero</span><span class="p">(</span><span class="n">T</span><span class="p">)</span>
<span class="p">@</span><span class="n">nloops</span> <span class="o">$</span><span class="n">N</span> <span class="n">i</span> <span class="n">A</span> <span class="k">begin</span>
<span class="n">s</span> <span class="o">+=</span> <span class="p">@</span><span class="n">nref</span> <span class="o">$</span><span class="n">N</span> <span class="n">A</span> <span class="n">i</span>
<span class="k">end</span>
<span class="n">s</span>
<span class="k">end</span>
<span class="k">end</span>
<span class="n">mysum_cache</span><span class="p">[</span><span class="n">N</span><span class="p">]</span> <span class="o">=</span> <span class="n">eval</span><span class="p">(</span><span class="k">quote</span>
<span class="kd">local</span> <span class="n">_F_</span>
<span class="o">$</span><span class="n">localfunc</span>
<span class="n">_F_</span>
<span class="k">end</span><span class="p">)</span>
<span class="k">end</span>
<span class="n">mysum_cache</span><span class="p">[</span><span class="n">N</span><span class="p">](</span><span class="n">A</span><span class="p">)::</span><span class="nb">typeof</span><span class="p">(</span><span class="n">A</span><span class="p">)</span>
<span class="k">end</span>
<span class="k">end</span>
<span class="k">end</span><span class="p">)</span>
</pre></div>
</div>
<p>You can see that <tt class="docutils literal"><span class="pre">@ngenerate</span></tt> causes explicit versions to be
generated for dimensions 1 to 4 (a setting controlled by the constant
<tt class="docutils literal"><span class="pre">CARTESIAN_DIMS</span></tt>). To allow arbitrary-dimensional arrays to be
handled, it also generates a version in which different methods are
cached in a dictionary. If a given method has not yet been generated,
it creates a version specific to that dimensionality and then stores
it in the dictionary. Creating the method is slow—it involves
generating expressions and then evaluating them—but once created the
function can be looked up from the cache, and is reasonably efficient
(but still less efficient than the versions generated for explicit
dimensionality).</p>
<p>The arguments to <tt class="docutils literal"><span class="pre">@ngenerate</span></tt> are:</p>
<ul class="simple">
<li>The symbol of the variable that will be used for generating
different versions (in the example, <tt class="docutils literal"><span class="pre">N</span></tt>)</li>
<li>The return type of the function (in the example,
<tt class="docutils literal"><span class="pre">typeof(A)</span></tt>). This is not used for the versions that are generated
for specific <tt class="docutils literal"><span class="pre">N</span></tt>, but is needed for the dictionary-backed
version. Julia cannot infer the return type of the function looked
up from the dictionary.</li>
<li>The actual function declaration. Use <tt class="docutils literal"><span class="pre">N</span></tt> as you would a normal
parameter.</li>
</ul>
</div>
<div class="section" id="anonymous-function-expressions-as-macro-arguments">
<h3>Anonymous-function expressions as macro arguments<a class="headerlink" href="#anonymous-function-expressions-as-macro-arguments" title="Permalink to this headline">¶</a></h3>
<p>Perhaps the single most powerful feature in <tt class="docutils literal"><span class="pre">Cartesian</span></tt> is the
ability to supply anonymous-function expressions that get evaluated at
parsing time. Let’s consider a simple example:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="p">@</span><span class="n">nexprs</span> <span class="mi">2</span> <span class="n">j</span><span class="o">-></span><span class="p">(</span><span class="n">i_j</span> <span class="o">=</span> <span class="mi">1</span><span class="p">)</span>
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">@nexprs</span></tt> generates <tt class="docutils literal"><span class="pre">n</span></tt> expressions that follow a pattern. This
code would generate the following statements:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">i_1</span> <span class="o">=</span> <span class="mi">1</span>
<span class="n">i_2</span> <span class="o">=</span> <span class="mi">1</span>
</pre></div>
</div>
<p>In each generated statement, an “isolated” <tt class="docutils literal"><span class="pre">j</span></tt> (the variable of the
anonymous function) gets replaced by values in the range <tt class="docutils literal"><span class="pre">1:2</span></tt>.
Generally speaking, Cartesian employs a LaTeX-like syntax. This
allows you to do math on the index <tt class="docutils literal"><span class="pre">j</span></tt>. Here’s an example computing
the strides of an array:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">s_1</span> <span class="o">=</span> <span class="mi">1</span>
<span class="p">@</span><span class="n">nexprs</span> <span class="mi">3</span> <span class="n">j</span><span class="o">-></span><span class="p">(</span><span class="n">s_</span><span class="p">{</span><span class="n">j</span><span class="o">+</span><span class="mi">1</span><span class="p">}</span> <span class="o">=</span> <span class="n">s_j</span> <span class="o">*</span> <span class="n">size</span><span class="p">(</span><span class="n">A</span><span class="p">,</span> <span class="n">j</span><span class="p">))</span>
</pre></div>
</div>
<p>would generate expressions</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">s_1</span> <span class="o">=</span> <span class="mi">1</span>
<span class="n">s_2</span> <span class="o">=</span> <span class="n">s_1</span> <span class="o">*</span> <span class="n">size</span><span class="p">(</span><span class="n">A</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
<span class="n">s_3</span> <span class="o">=</span> <span class="n">s_2</span> <span class="o">*</span> <span class="n">size</span><span class="p">(</span><span class="n">A</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
<span class="n">s_4</span> <span class="o">=</span> <span class="n">s_3</span> <span class="o">*</span> <span class="n">size</span><span class="p">(</span><span class="n">A</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>
</pre></div>
</div>
<p>Anonymous-function expressions have many uses in practice.</p>
<div class="section" id="macro-reference">
<span id="devdoc-cartesian-reference"></span><h4>Macro reference<a class="headerlink" href="#macro-reference" title="Permalink to this headline">¶</a></h4>
</div>
</div>
<div class="section" id="macros-for-creating-functions">
<h3>Macros for creating functions<a class="headerlink" href="#macros-for-creating-functions" title="Permalink to this headline">¶</a></h3>
<dl class="function">
<dt>
<tt class="descname">@ngenerate Nsym returntypeexpr functiondeclexpr</tt></dt>
<dd><p>Generate versions of a function for different values of <tt class="docutils literal"><span class="pre">Nsym</span></tt>.</p>
</dd></dl>
<dl class="function">
<dt>
<tt class="descname">@nsplat Nsym functiondeclexpr</tt></dt>
<dt>
<tt class="descname">@nsplat Nsym dimrange functiondeclexpr</tt></dt>
<dd><p>Generate explicit versions of a function for different numbers of
arguments. For example:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="p">@</span><span class="n">nsplat</span> <span class="n">N</span> <span class="mi">2</span><span class="p">:</span><span class="mi">3</span> <span class="n">absgetindex</span><span class="p">(</span><span class="n">A</span><span class="p">,</span> <span class="n">I</span><span class="p">::</span><span class="n">NTuple</span><span class="p">{</span><span class="n">N</span><span class="p">,</span><span class="n">Real</span><span class="p">}</span><span class="o">...</span><span class="p">)</span> <span class="o">=</span> <span class="n">abs</span><span class="p">(</span><span class="n">getindex</span><span class="p">(</span><span class="n">A</span><span class="p">,</span> <span class="n">I</span><span class="o">...</span><span class="p">))</span>
</pre></div>
</div>
<p>generates:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="n">absgetindex</span><span class="p">(</span><span class="n">A</span><span class="p">,</span> <span class="n">I_1</span><span class="p">::</span><span class="n">Real</span><span class="p">,</span> <span class="n">I_2</span><span class="p">::</span><span class="n">Real</span><span class="p">)</span> <span class="o">=</span> <span class="n">abs</span><span class="p">(</span><span class="n">getindex</span><span class="p">(</span><span class="n">A</span><span class="p">,</span> <span class="n">I_1</span><span class="p">,</span> <span class="n">I_2</span><span class="p">))</span>
<span class="n">absgetindex</span><span class="p">(</span><span class="n">A</span><span class="p">,</span> <span class="n">I_1</span><span class="p">::</span><span class="n">Real</span><span class="p">,</span> <span class="n">I_2</span><span class="p">::</span><span class="n">Real</span><span class="p">,</span> <span class="n">I_3</span><span class="p">::</span><span class="n">Real</span><span class="p">)</span> <span class="o">=</span> <span class="n">abs</span><span class="p">(</span><span class="n">getindex</span><span class="p">(</span><span class="n">A</span><span class="p">,</span> <span class="n">I_1</span><span class="p">,</span> <span class="n">I_2</span><span class="p">,</span> <span class="n">I_3</span><span class="p">))</span>
</pre></div>
</div>
</dd></dl>
</div>
<div class="section" id="macros-for-function-bodies">
<h3>Macros for function bodies<a class="headerlink" href="#macros-for-function-bodies" title="Permalink to this headline">¶</a></h3>
<dl class="function">
<dt>
<tt class="descname">@nloops N itersym rangeexpr bodyexpr</tt></dt>
<dt>
<tt class="descname">@nloops N itersym rangeexpr preexpr bodyexpr</tt></dt>
<dt>
<tt class="descname">@nloops N itersym rangeexpr preexpr postexpr bodyexpr</tt></dt>
<dd><p>Generate <tt class="docutils literal"><span class="pre">N</span></tt> nested loops, using <tt class="docutils literal"><span class="pre">itersym</span></tt> as the prefix for
the iteration variables. <tt class="docutils literal"><span class="pre">rangeexpr</span></tt> may be an
anonymous-function expression, or a simple symbol <tt class="docutils literal"><span class="pre">var</span></tt> in which
case the range is <tt class="docutils literal"><span class="pre">1:size(var,d)</span></tt> for dimension <tt class="docutils literal"><span class="pre">d</span></tt>.</p>
<p>Optionally, you can provide “pre” and “post” expressions. These
get executed first and last, respectively, in the body of each
loop. For example,</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="p">@</span><span class="n">nloops</span> <span class="mi">2</span> <span class="n">i</span> <span class="n">A</span> <span class="n">d</span><span class="o">-></span><span class="n">j_d</span><span class="o">=</span><span class="n">min</span><span class="p">(</span><span class="n">i_d</span><span class="p">,</span><span class="mi">5</span><span class="p">)</span> <span class="k">begin</span>
<span class="n">s</span> <span class="o">+=</span> <span class="p">@</span><span class="n">nref</span> <span class="mi">2</span> <span class="n">A</span> <span class="n">j</span>
<span class="k">end</span>
</pre></div>
</div>
<p>would generate</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="k">for</span> <span class="n">i_2</span> <span class="o">=</span> <span class="mi">1</span><span class="p">:</span><span class="n">size</span><span class="p">(</span><span class="n">A</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
<span class="n">j_2</span> <span class="o">=</span> <span class="n">min</span><span class="p">(</span><span class="n">i_2</span><span class="p">,</span> <span class="mi">5</span><span class="p">)</span>
<span class="k">for</span> <span class="n">i_1</span> <span class="o">=</span> <span class="mi">1</span><span class="p">:</span><span class="n">size</span><span class="p">(</span><span class="n">A</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
<span class="n">j_1</span> <span class="o">=</span> <span class="n">min</span><span class="p">(</span><span class="n">i_1</span><span class="p">,</span> <span class="mi">5</span><span class="p">)</span>
<span class="n">s</span> <span class="o">+=</span> <span class="n">A</span><span class="p">[</span><span class="n">j_1</span><span class="p">,</span><span class="n">j_2</span><span class="p">]</span>
<span class="k">end</span>
<span class="k">end</span>
</pre></div>
</div>
<p>If you want just a post-expression, supply
<tt class="docutils literal"><span class="pre">nothing</span></tt> for the pre-expression. Using parenthesis and
semicolons, you can supply multi-statement expressions.</p>
</dd></dl>
<dl class="function">
<dt>
<tt class="descname">@nref N A indexexpr</tt></dt>
<dd><p>Generate expressions like <tt class="docutils literal"><span class="pre">A[i_1,i_2,...]</span></tt>. <tt class="docutils literal"><span class="pre">indexexpr</span></tt> can
either be an iteration-symbol prefix, or an anonymous-function
expression.</p>
</dd></dl>
<dl class="function">
<dt>
<tt class="descname">@nexprs N expr</tt></dt>
<dd><p>Generate <tt class="docutils literal"><span class="pre">N</span></tt> expressions. <tt class="docutils literal"><span class="pre">expr</span></tt> should be an
anonymous-function expression.</p>
</dd></dl>
<dl class="function">
<dt>
<tt class="descname">@ntuple N expr</tt></dt>
<dd><p>Generates an <tt class="docutils literal"><span class="pre">N</span></tt>-tuple. <tt class="docutils literal"><span class="pre">@ntuple</span> <span class="pre">2</span> <span class="pre">i</span></tt> would generate <tt class="docutils literal"><span class="pre">(i_1,</span> <span class="pre">i_2)</span></tt>, and <tt class="docutils literal"><span class="pre">@ntuple</span> <span class="pre">2</span> <span class="pre">k->k+1</span></tt> would generate <tt class="docutils literal"><span class="pre">(2,3)</span></tt>.</p>
</dd></dl>
<dl class="function">
<dt>
<tt class="descname">@nall N expr</tt></dt>
<dd><p><tt class="docutils literal"><span class="pre">@nall</span> <span class="pre">3</span> <span class="pre">d->(i_d</span> <span class="pre">></span> <span class="pre">1)</span></tt> would generate the expression
<tt class="docutils literal"><span class="pre">(i_1</span> <span class="pre">></span> <span class="pre">1</span> <span class="pre">&&</span> <span class="pre">i_2</span> <span class="pre">></span> <span class="pre">1</span> <span class="pre">&&</span> <span class="pre">i_3</span> <span class="pre">></span> <span class="pre">1)</span></tt>. This can be convenient for
bounds-checking.</p>
</dd></dl>
<dl class="function">
<dt>
<tt class="descname">@nif N conditionexpr expr</tt></dt>
<dt>
<tt class="descname">@nif N conditionexpr expr elseexpr</tt></dt>
<dd><p>Generates a sequence of <tt class="docutils literal"><span class="pre">if</span> <span class="pre">...</span> <span class="pre">elseif</span> <span class="pre">...</span> <span class="pre">else</span> <span class="pre">...</span> <span class="pre">end</span></tt> statements. For example:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="p">@</span><span class="n">nif</span> <span class="mi">3</span> <span class="n">d</span><span class="o">-></span><span class="p">(</span><span class="n">i_d</span> <span class="o">>=</span> <span class="n">size</span><span class="p">(</span><span class="n">A</span><span class="p">,</span><span class="n">d</span><span class="p">))</span> <span class="n">d</span><span class="o">-></span><span class="p">(</span><span class="nb">error</span><span class="p">(</span><span class="s">"Dimension "</span><span class="p">,</span> <span class="n">d</span><span class="p">,</span> <span class="s">" too big"</span><span class="p">))</span> <span class="n">d</span><span class="o">-></span><span class="n">println</span><span class="p">(</span><span class="s">"All OK"</span><span class="p">)</span>
</pre></div>
</div>
<p>would generate:</p>
<div class="highlight-julia"><div class="highlight"><pre><span class="k">if</span> <span class="n">i_1</span> <span class="o">></span> <span class="n">size</span><span class="p">(</span><span class="n">A</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
<span class="nb">error</span><span class="p">(</span><span class="s">"Dimension "</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="s">" too big"</span><span class="p">)</span>
<span class="k">elseif</span> <span class="n">i_2</span> <span class="o">></span> <span class="n">size</span><span class="p">(</span><span class="n">A</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
<span class="nb">error</span><span class="p">(</span><span class="s">"Dimension "</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="s">" too big"</span><span class="p">)</span>
<span class="k">else</span>
<span class="n">println</span><span class="p">(</span><span class="s">"All OK"</span><span class="p">)</span>
<span class="k">end</span>
</pre></div>
</div>
</dd></dl>
</div>
<div class="section" id="frequently-asked-questions">
<h3>Frequently asked questions<a class="headerlink" href="#frequently-asked-questions" title="Permalink to this headline">¶</a></h3>
<div class="section" id="i-got-an-error-error-n-not-defined-when-using-ngenerate-why">
<h4>I got an error <tt class="docutils literal"><span class="pre">ERROR:</span> <span class="pre">N</span> <span class="pre">not</span> <span class="pre">defined</span></tt> when using <tt class="docutils literal"><span class="pre">@ngenerate</span></tt>. Why?<a class="headerlink" href="#i-got-an-error-error-n-not-defined-when-using-ngenerate-why" title="Permalink to this headline">¶</a></h4>
<p>Most likely you forgot to define your function with <tt class="docutils literal"><span class="pre">N</span></tt> as a type parameter, e.g., <tt class="docutils literal"><span class="pre">@ngenerate</span> <span class="pre">N</span> <span class="pre">returntype</span> <span class="pre">myfunc{N}(...)</span></tt>.</p>
</div>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="sysimg.html" class="btn btn-neutral float-right" title="System Image Building"/>Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="julia.html" class="btn btn-neutral" title="Documentation of Julia’s Internals"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
</p>
</div>
<a href="https://github.com/snide/sphinx_rtd_theme">Sphinx theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../',
VERSION:'0.3.4',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/javascript" src="../_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
