Copyright © 1996-2013 John W. Eaton.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.

[Top] [Contents] [Index] [ ? ]

GNU Octave

This manual documents how to run, install and port GNU Octave, as well as its new features and incompatibilities, and how to report bugs. It corresponds to GNU Octave version 3.8.2.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Preface

Octave was originally intended to be companion software for an undergraduate-level textbook on chemical reactor design being written by James B. Rawlings of the University of Wisconsin-Madison and John G. Ekerdt of the University of Texas.

Clearly, Octave is now much more than just another ‘courseware’ package with limited utility beyond the classroom. Although our initial goals were somewhat vague, we knew that we wanted to create something that would enable students to solve realistic problems, and that they could use for many things other than chemical reactor design problems. We find that most students pick up the basics of Octave quickly, and are using it confidently in just a few hours.

Although it was originally intended to be used to teach reactor design, it has been used in several other undergraduate and graduate courses in the Chemical Engineering Department at the University of Texas, and the math department at the University of Texas has been using it for teaching differential equations and linear algebra as well. More recently, Octave has been used as the primary computational tool for teaching Stanford’s online Machine Learning class (ml-class.org) taught by Andrew Ng. Tens of thousands of students participated in the course.

If you find Octave useful, please let us know. We are always interested to find out how Octave is being used.

Virtually everyone thinks that the name Octave has something to do with music, but it is actually the name of one of John W. Eaton’s former professors who wrote a famous textbook on chemical reaction engineering, and who was also well known for his ability to do quick ‘back of the envelope’ calculations. We hope that this software will make it possible for many people to do more ambitious computations just as easily.

Everyone is encouraged to share this software with others under the terms of the GNU General Public License (see section GNU GENERAL PUBLIC LICENSE). You are also encouraged to help make Octave more useful by writing and contributing additional functions for it, and by reporting any problems you may have.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Acknowledgements

Many people have contributed to Octave’s development. The following people have helped code parts of Octave or aided in various other ways (listed alphabetically).

Ben AbbottAndy AdlerAdam H. Aitkenhead
Giles AndersonJoel AnderssonMuthiah Annamalai
Markus AppelBranden ArcherMarco Atzeri
Shai AyalRoger BanksBen Barrowes
Alexander BarthDavid BatemanHeinz Bauschke
Julien BectRoman BelovKarl Berry
David BillinghurstDon BindnerJakub Bogusz
Moritz BorgmannPaul BovenRichard Bovey
John BradshawMarcus BrinkmannMax Brister
Remy BrunoClemens BuchacherAnsgar Burchard
Marco CaliariDaniel CalveloJohn C. Campbell
Juan Pablo CarbajalJean-Francois CardosoJoao Cardoso
Larrie CarrDavid CastelowVincent Cautaerts
Clinton CheeAlbert Chin-A-YoungCarsten Clark
Catalin CodreanuJ. D. ColeMartin Costabel
Michael CreelRichard CrozierJeff Cunningham
Martin DaleckiJacob DawidJorge Barros de Abreu
Carlo de FalcoThomas D. DeanPhilippe Defert
Bill DenneyFabian DeutschChristos Dimitrakakis
Pantxo DiribarneVivek DograJohn Donoghue
David M. DoolinCarnë DraugPascal A. Dupuis
John W. EatonDirk EddelbuettelPieter Eendebak
Paul EggertStephen EglenPeter Ekberg
Rolf FabianGunnar FarnebäckStephen Fegan
Ramon Garcia FernandezTorsten FinkeJose Daniel Munoz Frias
Brad FroehleCastor FuEduardo Gallestey
Walter GautschiKlaus GebhardtDriss Ghaddab
Nicolo GiorgettiArun GiridharMichael D. Godfrey
Michael GoffioulGlenn GoldenTomislav Goles
Keith GoodmanBrian GoughSteffen Groot
Etienne GrossmannDavid GrundbergKyle Guinn
Peter GustafsonKai HabelPatrick Häcker
William P. Y. HadisoesenoJaroslav HajekBenjamin Hall
Kim HansenSøren HaubergDave Hawthorne
Daniel HeisererMartin HelmStefan Hepp
Martin HepperleJordi Gutiérrez HermosoYozo Hida
Ryan HintonRoman HodekA. Scottedward Hodel
Richard Allan HolcombeTom HolroydDavid Hoover
Kurt HornikChristopher HulbertCyril Humbert
John HuntTeemu IkonenAlan W. Irwin
Geoff JacobsenMats JanssonCai Jianming
Steven G. JohnsonHeikki JunesMatthias Jüschke
Atsushi KajitaJarkko KalevaMohamed Kamoun
Lute KamstraFotios KasolisThomas Kasper
Joel KeayMumit KhanPaul Kienzle
Aaron A. KingErik KjellsonArno J. Klaassen
Alexander KleinGeoffrey KnauthHeine Kolltveit
Ken KounoKacper KowalikDaniel Kraft
Nir KrakauerAravindh KrishnamoorthyOyvind Kristiansen
Artem KrosheninnikovPiotr KrzyzanowskiVolker Kuhlmann
Tetsuro KuritaPhilipp KutinMiroslaw Kwasniak
Rafael LaboissiereKai LabuschClaude Lacoursiere
Walter LandryBill LashDirk Laurie
Maurice LeBrunFriedrich LeischThorsten Liebig
Jyh-miin LinTimo LindforsBenjamin Lindner
Ross LippertDavid LivingsSebastien Loisel
Erik de Castro LopoMassimo LorenzinEmil Lucretiu
Hoxide MaColin MacdonaldJames Macnicol
Jens-Uwe MagerRob MahurinAlexander Mamonov
Ricardo MarranitaOrestes MasAxel Mathéi
Makoto MatsumotoTatsuro MatsuokaChristoph Mayer
Laurent MazetG. D. McBainRonald van der Meer
Júlio Hoffimann MendesEd MeyerThorsten Meyer
Petr MikulikMike MillerStefan Monnier
Antoine MoreauKai P. MuellerHannes Müller
Victor MunozIain MurrayCarmen Navarrete
Todd NealPhilip NienhuisAl Niessner
Felipe G. NievinskiRick NilesTakuji Nishimura
Kai NodaPatrick NoffkeEric Norum
Krzesimir NowakMichael O’BrienPeter O’Gorman
Thorsten OhlArno OnkenValentin Ortega-Clavero
Luis F. OrtizCarl OsterwischJanne Olavi Paanajärvi
Scott PakinGabriele PannocchiaSylvain Pelissier
Per PerssonPrimozz PeterlinJim Peterson
Danilo PiazzalungaNicholas PiperElias Pipping
Robert PlattHans Ekkehard PlesserTom Poage
Orion PoplawskiOndrej PoppJef Poskanzer
Francesco PotortìKonstantinos PouliosJarno Rajahalme
James B. RawlingsEric S. RaymondBalint Reczey
Joshua RedstoneLukas ReichlinMichael Reifenberger
Jens RestemeierAnthony RichardsonJason Riedy
E. Joshua RiglerSander van RijnPetter Risholm
Matthew W. RobertsPeter RosinAndrew Ross
Fabio RossiMark van RossumJoe Rothweiler
Kevin RulandKristian RumbergRyan Rusaw
Olli SaarelaToni SaarelaJuhani Saastamoinen
Radek SalacBen SappAleksej Saushev
Alois SchlöglMichel D. SchmidJulian Schnidder
Nicol N. SchraudolphSebastian SchubertLudwig Schwardt
Thomas L. ScofieldDaniel J. SebaldDmitri A. Sergatskov
Vanya SergeevBaylis ShanksAndriy Shinkarchuck
Robert T. ShortJoseph P. SkudlarekJohn Smith
Julius SmithShan G. SmithPeter L. Sondergaard
Joerg SpechtQuentin H. SpencerChristoph Spiel
Richard StallmanRussell StandishBrett Stewart
Doug StewartJonathan StickelJudd Storrs
Thomas StuartIvan SutorisJohn Swensen
Daisuke TakagoAriel TankusFalk Tannhäuser
Duncan Temple LangMatthew TennyKris Thielemans
Georg ThimmCorey ThomassonOlaf Till
Christophe TourneryThomas TreichlKarsten Trulsen
David TurnerFrederick UmmingerUtkarsh Upadhyay
Stefan van der WaltPeter Van WierenJames R. Van Zandt
Risto VanhanenGregory VanuxemMihas Varantsou
Ivana VarekovaSébastien VillemotDaniel Wagenaar
Thomas WalterAndreas WeberOlaf Weber
Thomas WeberRik WehbringBob Weigel
Andreas WeingesselMartin WeiserMichael Weitzel
David WellsFook Fah YapSean Young
Michael ZeisingFederico ZenithAlex Zvoleff

Special thanks to the following people and organizations for supporting the development of Octave:

This project would not have been possible without the GNU software used in and to produce Octave.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Citing Octave in Publications

In view of the many contributions made by numerous developers over many years it is common courtesy to cite Octave in publications when it has been used during the course of research or the preparation of figures. The citation function can automatically generate a recommended citation text for Octave or any of its packages. See the help text below on how to use citation.

Command: citation
Command: citation package

Display instructions for citing GNU Octave or its packages in publications.

When called without an argument, display information on how to cite the core GNU Octave system. When given a package name package, display information on citing the specific named package. Note that some packages may not yet have instructions on how to cite them.

The GNU Octave developers and its active community of package authors have invested a lot of time and effort in creating GNU Octave as it is today. Please give credit where credit is due and cite GNU Octave and its packages when you use them.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

How You Can Contribute to Octave

There are a number of ways that you can contribute to help make Octave a better system. Perhaps the most important way to contribute is to write high-quality code for solving new problems, and to make your code freely available for others to use. See section Contributing Guidelines, for detailed information on contributing new code.

If you find Octave useful, consider providing additional funding to continue its development. Even a modest amount of additional funding could make a significant difference in the amount of time that is available for development and support.

Donations supporting Octave development may be made on the web at https://my.fsf.org/donate/working-together/octave. These donations also help to support the Free Software Foundation

If you’d prefer to pay by check or money order, you can do so by sending a check to the FSF at the following address:

Free Software Foundation
51 Franklin Street, Suite 500
Boston, MA 02110-1335
USA

If you pay by check, please be sure to write “GNU Octave” in the memo field of your check.

If you cannot provide funding or contribute code, you can still help make Octave better and more reliable by reporting any bugs you find and by offering suggestions for ways to improve Octave. See section Known Causes of Trouble, for tips on how to write useful bug reports.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Distribution

Octave is free software. This means that everyone is free to use it and free to redistribute it on certain conditions. Octave is not, however, in the public domain. It is copyrighted and there are restrictions on its distribution, but the restrictions are designed to ensure that others will have the same freedom to use and redistribute Octave that you have. The precise conditions can be found in the GNU General Public License that comes with Octave and that also appears in GNU GENERAL PUBLIC LICENSE.

To download a copy of Octave, please visit http://www.octave.org/download.html.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1. A Brief Introduction to Octave

GNU Octaveは主に数値計算を意図した、ハイレベル言語であり、通常は線形、および非線形の代数、数値線形代数(numerical linear algebra)、統計分析を解決したり、その他の数値実験(numerical experiment)を行なうために使用されます。また、自動化されたデータ処理のための、バッチ指向言語としても使用されます。

最近まで、GNU Octaveは別ウィンドウでグラフィカルな結果を表示する、コマンドラインインターフェイスを提供していました。最新のバージョン(2013年後半にリリースされたバージョン3.8)は、デフォルトではグラフィカルユーザーインターフェイスも提供します。

GNU Octaveは自由に再頒布できるソフトウェアです。Free Software Foundationから公表されたGNU General Public Licenseの条件に基づき、あなたはこれを再頒布、かつ/または改変することができます。GPLは、このマニュアルのsee section GNU GENERAL PUBLIC LICENSEに含まれています。

このマニュアルはGNU Octaveのインストール、実行、使用に関する包括的なドキュメントを提供します。バグ報告やコードの寄贈については、追加のチャプターで説明します。

このドキュメントは、Octave バージョン3.8.2に対応します。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 Running Octave

大部分のシステムでは、シェルコマンド‘octave’によりOctaveが起動されます。デフォルトでは、このコマンドによりグラフィカルユーザーインターフェイス(GUI)が起動します。このGUIの中の中央のウィンドウは、Octaveのコマンドラインインターフェイスです。Octaveは初期メッセージを表示してから、入力を受け取る準備ができたことを示すプロンプトを表示します。伝統的なコマンドラインインターフェイスを選択していた場合には、コマンドプロンプトだけが表示されます。どちらの場合でも、すぐにOctaveコマンドのタイプを開始できます。

問題が起きた場合、通常はControl-C(略記はC-c)をタイプすることにより、Octaveに割り込むことができます。C-cの名前は、<CTRL>を押したまま<c>を押すという事実が由来です。これを行なうことにより、通常はOctaveのプロンプトに戻ることができるでしょう。

Octaveを終了するには、Octaveのプロンプトでquit、または, exitとタイプします。

ジョブ制御をサポートするシステムでは、通常はC-zとタイプしてSIGTSTPシグナルを送ることにより、Octaveをサスペンドすることができます。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 Simple Examples

以降のチャプターでは、Octaveのもつすべての機能の詳細を説明しますが、その前にOctaveの能力を示すサンプルを見ておくことが助けになるかもしれません。

Octaveに触れるのが初めてならば、これらのサンプルを試して実際にOctaveを使ってみることから、Octaveの学習を開始することをおすすめします。‘octave:13>’のようにマークされたラインは、あなたがタイプして最後にエンターで終了するラインです。するとOctaveは答えを示すか、グラフを表示するでしょう。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.1 Elementary Calculations

Octaveでは、基本的な数値計算を簡単に行うことができ、算術演算子(+,-,*,/)、べき乗(^)、対数と指数(log, exp)、三角関数(sin, cos, …)を認識します。さらにOctaveでの演算は実数に加えて虚数(i,j)にも機能します。また、自然対数の底(e)や円周率(pi)などの数学定数が事前に定義されています。

たとえばオイラーの等式

 
 i*pi
e     = -1

を検証するためには、以下をタイプすると、これは計算の許容誤差(tolerance of the calculation)とともに-1に評価されるでしょう。

 
octave:1> exp (i*pi)

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.2 Creating a Matrix

ベクターとマトリクスは、数値解析における基本的な構成要素です。新たにマトリクスを作成して、それを変数に格納すれば、コマンドをタイプして後からそれを参照できます

 
octave:1> A = [ 1, 1, 2; 3, 5, 8; 13, 21, 34 ]

Octaveは、列で整列されたマトリクスを表示して応答するでしょう。 Octave will respond by printing the matrix in neatly aligned columns.

Octaveは行の中の区切りにカンマ、またはスペースを使い、行ごとの区切りにはセミコロン、または改行を使用します。コマンドの最後にセミコロンを入力した場合、Octaveはコマンドの結果をプリントしません。たとえば、

 
octave:2> B = rand (3, 2);

これは、それぞれの要素が0から1の間の乱数であるような、3行2列のマトリクスを作成します。

変数の値を表示するには、プロンプトで、単に変数名をタイプします。たとえばBに格納されたマトリクスの値を表示するには、以下のコマンドをタイプします

 
octave:3> B

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.3 Matrix Arithmetic

Octaveには、行列演算を行なうための、便利な演算子があります。たとえばマトリクスAにスカラー値を乗ずるには、以下のコマンドを試してみてください

 
octave:4> 2 * A

2つの行列ABの内積は、以下のコマンドをタイプします

 
octave:5> A * B

行列の積 transpose (A) * A, を得るには、以下のコマンドをタイプします

 
octave:6> A' * A

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.4 Solving Systems of Linear Equations

数値解析において、線形方程式系(systems of linear equations)は至るところに現れます。一連の線形方程式Ax = bを解くには、左除算演算子(left division operator) ‘\’を使います:

 
x = A \ b

これは、概念的には以下と等価です inv (a) * b, しかし、左除算演算子を使うことにより、逆行列を直接計算するのを避けることができます。

係数行列(coefficient matrix)が正則(singular)な場合、Octaveは警告をプリントして、最小ノルム解(minimum norm solution)を計算します。

化学から簡単な例を1つ。バランスのとれた化学反応式(balanced chemical equations)を得たいとします。水素と酸素の燃焼による水の生成を考えてみましょう。

 
H2 + O2 --> H2O

この化学反応式は正確ではありません。質量保存の法則により、各分子の数は反応式の左辺と右辺でバランスが取れている必要があります。反応を通じて水素と酸素について個別に方程式を記述すると、以下のようになります:

 
x1*H2 + x2*O2 --> H2O
H: 2*x1 + 0*x2 --> 2
O: 0*x1 + 2*x2 --> 1

Octaveでは、3つのステップだけでこれを解くことができます。

 
octave:1> A = [ 2, 0; 0, 2 ];
octave:2> b = [ 2; 1 ];
octave:3> x = A \ b

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.5 Integrating Differential Equations

Octaveには、以下の形式をもち

 
dx
-- = f (x, t)
dt

初期条件が以下であるような非線形方程式を解くビルトイン関数があります

 
x(t = t0) = x0

このような形式の関数をOctaveで積分するには、最初にその関数の定義を与えなければなりません f(x,t). これは簡単です。コマンドライン上で関数のボディを直接入力していけばよいのです。たとえば、以下のコマンドは、ある非線形微分方程式の着目する変数ペアにたいする右辺の関数を定義しています。関数を入力する間、Octaveは異なるプロンプトで応答することに注意してください。これは入力が完了するまでOctaveが待機していることを示します。

 
octave:1> function xdot = f (x, t) 
>
>  r = 0.25;
>  k = 1.4;
>  a = 1.5;
>  b = 0.16;
>  c = 0.9;
>  d = 0.8;
>
>  xdot(1) = r*x(1)*(1 - x(1)/k) - a*x(1)*x(2)/(1 + b*x(1));
>  xdot(2) = c*a*x(1)*x(2)/(1 + b*x(1)) - d*x(2);
>
> endfunction

次に初期条件を与えます

 
octave:2> x0 = [1; 2];

そして出力時間を列ベクトルとしてセットします(1番目の出力時間は上記で与えた初期条件に対応することに注意してください)

 
octave:3> t = linspace (0, 50, 200)';

微分方程式の組を積分するのは簡単です:

 
octave:4> x = lsode ("f", x0, t);

関数lsodeは、「A. C. Hindmarsh, ODEPACK, a Systematized Collection of ODE Solvers, in: Scientific Computing, R. S. Stepleman et al. (Eds.), North-Holland, Amsterdam, 1983」の55ページから64ページで説明されている、"Livermore Solver for Ordinary Differential Equation"を使用しています。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.6 Producing Graphical Output

前の例の解をグラフィカルに表示するには、以下のコマンドを使用します

 
octave:1> plot (t, x)

グラフィカルユーザーインターフェイスを使用している場合、Octaveはプロットを表示するための別ウィンドウを自動的に作成するでしょう。

1度スクリーンに表示されたプロットを保存するには、printコマンドを使用します。たとえば、

 
print -deps foo.eps

Encapsulated PostScriptフォーマットで描画された現在のプロットを含む、‘foo.eps’というファイルを作成します。また、以下のコマンド

 
help print

は、printにたいする他のオプションの説明と、出力ファイルフォーマットの追加リストを提供します。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.7 Editing What You Have Typed

Octaveプロンプトでは、Emacsスタイル、またはviスタイルを使用した、以前のコマンドの再呼び出し、編集、再実行が可能です。デフォルトのキーバインディングは、Emacsスタイルのコマンドを使用します。たとえば、前のコマンドを再び呼び出すには、Control-p(略記するとC-p)を押します。これを行なうことにより、入力した以前の行に戻ることができます。他にも、C-nで入力の次の行、C-bでカーソルをその行の後方へ移動、C-fでカーソルをその行の前方へ移動などができます。

コマンドライン編集の能力に関する完全な説明は、このマニュアルのsee section Command Line Editingで提供されています。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2.8 Help and Documentation

Octaveには豊富なヘルプ機能があります。Octaveプロンプトから、同じドキュメントのプリント形式が利用できます。これはドキュメントの各形式が、同じ入力ファイルから作成されているからです。

望ましいヘルプを得るには、まず使いたいコマンドの名前を知る必要があります。この関数の名前が明確でない場合もあります。そのようなときは、help --listとタイプするのがよい出発点です。これはすべての演算子、キーワード、ビルトイン関数、Octaveのカレントセッションで利用できるロード可能な関数をすべて表示します。代替としては、lookfor関数を使ってドキュメントを検索する方法もあります。この関数は、Commands for Getting Helpで説明されています。

使いたい関数の名前が解ったら、単にhelpの引数にその関数の名前を含めることで、さらなるヘルプを入手できます。たとえば、

 
help plot

これはplot関数のヘルプテキストを表示します。

Octaveは、1つのスクリーンに収まらないような長い出力を、lessmore風のページャーを通じて送ります。<RET>をタイプすると1行、<SPC>で1ページ進み、<q>でページャーを抜けます。

Octave内ででプリントされたマニュアルの完全なテキストを読むことができるOctaveのヘルプ機能の一部は、通常はInfoと呼ばれる別のプログラムを使用します。Infoを呼び出すと、Octaveマニュアル全体を含んだメニュー駆動型のプログラムが起動されます。Infoの使用に関するヘルプは、このマニュアルのsee section Commands for Getting Helpで提供されています。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 Conventions

このセクションでは、このマニュアルで使われている表記規約について説明します。あなたはこのセクションを飛ばして、あとで参照したいと思うかもしれません。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3.1 Fonts

Octaveコードの例は、svd (a)のようなフォントまたは形式で表します。変数や関数の引数の名前を示す場合は、first-numberのようなフォントまたは形式で表します。シェルプロンプト上でタイプするコマンドは、‘octave --no-init-file’のようなフォントまたは形式で表します。Octaveプロンプト上でタイプするコマンドは、foo --bar --bazのようなフォントまたは形式で表す場合があります。キーボード上の特定のキーは、<ANY>のようなフォントまたは形式で表します。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3.2 Evaluation Notation

このマニュアル内の例では、あなたが評価した式の結果は、‘’で示されます。たとえば、

 
sqrt (2)
     ⇒ 1.4142

あなたはこれを、“sqrt (2)は1.4142に評価された”と読み替えることができます。

式によりリターンされるマトリクス値は、以下のように表示される場合があります

 
[1, 2; 3, 4] == [1, 3; 2, 4]
     ⇒ [ 1, 0; 0, 1 ]

また、以下のように表示される場合もあります

 
eye (3)
     ⇒  1  0  0
         0  1  0
         0  0  1

これは結果の構造を明確にするためです。

1つの式を説明するのに、同じ結果を生成する別の式を示すのが助けになる場合もあります。式の完全な等価は、‘’で表します。たとえば:

 
rot90 ([1, 2; 3, 4], -1)
≡
rot90 ([1, 2; 3, 4], 3)
≡
rot90 ([1, 2; 3, 4], 7)

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3.3 Printing Notation

このマニュアルの例の多くは、評価されたときにテキストをプリントします。このマニュアルでは、例の結果としてプリントされるものを、‘-|’で表します。式の評価によりリターンされた値(次の例の1)は、続けて別の行に‘’で表します。

 
printf ("foo %s\n", "bar")
     -| foo bar
     ⇒ 1

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3.4 Error Messages

エラーをシグナルする例もいくつかあります。これらは通常、端末上にエラーメッセージを表示します。エラーメッセージは行頭のerror:で表します。

 
fieldnames ([1, 2; 3, 4])
error: fieldnames: Invalid input argument

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3.5 Format of Descriptions

このマニュアルでは、関数とコマンドは統一されたフォーマットで説明されています。説明の最初の行には、そのアイテムの名前と、もしあれば引数が含まれます。 行の先頭はカテゴリー—function、commandなど—が表示されます。 後続の行が説明で、例を含む場合もあります。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3.5.1 A Sample Function Description

関数の説明では、説明される関数の名前が最初に表示されます。同じ行にパラメーターのリストが続きます。パラメーターに使用された名前は、説明の本文でも使用されます。

以下は、架空の関数fooの説明です:

Function File: foo (x)
Function File: foo (x, y)
Function File: foo (x, y, …)

関数fooyからxを減じたのち、残りの引数を結果に加算します。yが与えられない場合、デフォルトとして数値19が使用されます。

 
foo (1, [3, 5], 3, 9)
     ⇒ [ 14, 16 ]
foo (5)
     ⇒ 14

より一般的には、

 
foo (w, x, y, …)
≡
x - w + y + …

名前に型名(例: integermatrix)を含むパラメーターは、その型が期待されます。objectという名前のパラメーターは、任意の型です。他の種類の名前(例: new_file)をもつパラメーターについては、その関数の説明の中で個別に説明されます。いくつかのセクションでは、複数の関数で共通のパラメーターは、最初に説明されます。

Octave内の関数は、複数の異なる方法で定義されているかもしれません。関数のカテゴリー名には、その関数が定義された方法を示す他の名前が含まれる場合があります。これらの追加タグには以下が含まれます。

Function File

説明されている関数は、テキストファイルに格納されたOctaveコマンドにより定義されています。Function Filesを参照してください。

Built-in Function

説明されている関数は、C++、C、またはFortranのような言語で記述されており、コンパイル済みOctaveバイナリーの一部です。

Loadable Function

説明されている関数は、C++、C、またはFortranのような言語で記述されています。ユーザー定義関数の動的リンクをサポートするシステムでは、Octaveの実行中に、必要なときだけ自動的にリンクされます。

Mapping Function

説明されている関数は、マトリクスおよびベクター引数の要素ごとに作用します。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3.5.2 A Sample Command Description

コマンドの説明は、単語‘Function’が‘Command’置き換わることを除き、関数の説明と同じフォーマットです。コマンドとは、引数をカッコで括らずに呼び出される関数です。たとえば、以下はOctaveのcdコマンドの説明です。

Command: cd dir
Command: chdir dir

カレント作業ディレクトリーをdirに変更します。たとえばcd ~/octaveは、カレント作業ディレクトリーを‘~/octave’に変更します。そのディレクトリーが存在しない場合、エラーメッセージをプリントし、作業ディレクトリーは変更されません。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2. Getting Started

このチャプターでは、Octaveの基本的な機能についていくつか説明します。それらの機能にはOctaveセッションの開始、コマンドプロンプトでのヘルプの入手、コマンド行の編集、シェルプロンプトからコマンドとして実行可能なOctaveプログラムの記述が含まれます。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1 Invoking Octave from the Command Line

Octaveは通常、引数を指定せずに‘octave’プログラムを実行することにより、対話的に使用されます。一度開始すると、exitを指示するまで、Octaveは端末からコマンドを読み取ります。

コマンドラインにファイル名を指定することもできます。この場合、Octaveはその名前のファイルからコマンドを読み込んで実行し、それが終了したらexitします。

さらに次のセクションで説明するコマンドラインオプションにより、Octaveをどのように開始するか、制御することができます。Octave自身が、利用できるオプションを知らせることができます。‘octave --help’(短い形式は‘octave -h’)とタイプすると、利用できるすべてのオプションと、使い方の簡略が表示されます。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1.1 Command Line Options

以下は、Octaveに指定できるコマンドラインオプションの、完全なリストです。

--built-in-docstrings-file filename

Octaveのビルトイン関数のドキュメント文字列を含むファイルの名前を指定します。この値は通常は正しいので、異常な状況において指定する必要なときだけ指定するべきです。

--debug
-d

パーサーのデバッグモードに入ります。このオプションを使うことにより、Octaveが読み込んだコマンドについて、Octaveパーサーが大量の情報をプリントするようになるので、おそらくパーサーのデバッグを実際に試みるときだけ有用でしょう。

--debug-jit

JITコンパイラーのデバッグとトレースを有効にします。

--doc-cache-file filename

使用するドキュメントキャッシュファイルを指定します。コマンドラインで指定されたfilenameの値は、環境変数OCTAVE_DOC_CACHE_FILEの値をオーバーライドします。しかし、doc_cache_fileを使用する、システムまたはユーザーのスタートアップファイルのコマンドを除きます。

--echo-commands
-x

コマンドが実行されると、そのコマンドをエコーします。

--eval code

codeを評価して、‘--persist’が共に指定されていなければ、評価の終了と共にexitします。

--exec-path path

実行するプログラムうぃ検索するパスを指定します。コマンドラインで指定されたpathの値は、環境変数OCTAVE_EXEC_PATHの値をオーバーライドします。しかし、ビルトイン変数EXEC_PATHをセットする、システムまたはユーザーのスタートアップファイルのコマンドを除きます。

--force-gui

起動時にグラフィカルユーザーインターフェイス(FUI)を強制します。

--help
-h
-?

短いヘルプメッセージをプリントして、exitします。

--image-path path

イメージを検索するパスのheadにパスを追加します。コマンドラインで指定されたpathの値は、環境変数OCTAVE_IMAGE_PATHの値をオーバーライドします。しかし、ビルトイン変数IMAGE_PATHをセットする、システムまたはユーザーのスタートアップファイルのコマンドを除きます。

--info-file filename

使用するinfoファイルの名前を指定します。コマンドラインでfilenameに指定された値は、環境変数OCTAVE_INFO_FILEの値をオーバーライドします。しかし、info_file関数を使用する、システムまたはユーザーのスタートアップファイルのコマンドを除きます。

--info-program program

使用するinfoプログラムの名前を指定します。コマンドラインで指定されたprogramの値は、環境変数OCTAVE_INFO_PROGRAMの値をオーバーライドします。しかし、info_program関数を使用する、システムまたはユーザーのスタートアップファイルのコマンドを除きます。

--interactive
-i

対話的な動作を強制します。これはリモートシェルコマンドやEmacsのシェルバッファーを通じてOctaveを実行するとき便利かもしれません。

--jit-compiler

JITコンパイラーのループ高速化を有効にします。

--line-editing

コマンドライン編集に、readlineの使用を強制します。

--no-gui

グラフィカルユーザーインターフェイス(GUI)を無効にして、かわりにコマンドラインインターフェイス(CLI)を使用します。

--no-history
-H

コマンドラインのヒストリーの記録を無効にします。

--no-init-file

初期化ファイル‘~/.octaverc’および‘.octaverc’を読み込みません。

--no-init-path

デフォルトの場所を含めるための、関数ファイル用の検索パス初期化を行いません。

--no-line-editing

コマンドライン編集を無効にします。

--no-site-file

サイト単位の初期化ファイル‘octaverc’を読み込みません。

--no-window-system
-W

グラフィックスを含めてウィンドウシステムの使用を無効にします。これは端末だけに制限された環境を強制します。

--norc
-f

スタートアップ時に、システムまたはユーザーの初期化ファイルを読み込みません。これは、‘--no-init-file’と‘--no-site-file’の両方のオプションを使用することと同じです。

--path path
-p path

関数ファイルの検索パスにheadにパスを追加します。コマンドラインで指定されたpathの値は、環境変数OCTAVE_PATHの値をオーバーライドします。しかしシステムまたはユーザーのスタートアップファイルで、path関数のいずれかを通じてセットされた内部のloadパスは除きます。

--persist

--eval’またはコマンドラインで指定された名前のファイルを読み込んだ後に、インタラクティブモードに移ります。

--silent
--quiet
-q

起動時に通常のグリーティングメッセージとバージョンメッセージをプリントしません。

--texi-macros-file filename

makeinfoにより使用されるTexinfoマクロを含むファイルの名前を指定します。

--traditional
--braindead

MATLABとの互換のために、ユーザープリファレンスとして、以下の値を初期値としてセットします。

 
PS1                             = ">> "
PS2                             = ""
allow_noninteger_range_as_index = true
beep_on_error                   = true
confirm_recursive_rmdir         = false
crash_dumps_octave_core         = false
save_default_options            = "-mat-binary"
do_braindead_shortcircuit_evaluation = true
fixed_point_format              = true
history_timestamp_format_string = "%%-- %D %I:%M %p --%%"
page_screen_output              = false
print_empty_dimensions          = false

そして、以下の警告を無効にします。

 
Octave:abbreviated-property-match
Octave:fopen-file-in-path
Octave:function-name-clash
Octave:load-file-in-path

これはOctave:matlab-incompatible警告を有効にしないことに注意してください。Octaveでは機能するが、MATLABでは機能しないコードの記述にたいして警告してほしいときは、この警告を有効にしたいと思うでしょう(詳細はwarning、およびwarning_idsを参照してください)。

--verbose
-V

詳細な出力に切り替えます。

--version
-v

プログラムのバージョンナンバーをプリントしてexitします。

file

fileのコマンドを実行します。‘--persist’が指定されていない場合は、実行が終了した後にexitします。

Octaveには、引数の数やすべてのオプションなど、コマンドラインの情報についてリターンする関数がいくつかあります。

Built-in Function: argv ()

Octaveに渡されたコマンドライン引数をリターンします。たとえば以下のようなコマンドを使用してOctaveを呼び出した場合、

 
octave --no-line-editing --silent

argvは、要素が‘--no-line-editing’と‘--silent’であるようなセル配列をリターンするでしょう。

実行可能なOctaveスクリプトを記述した場合、argvはそのスクリプトに渡された引数のリストをリターンします。実行可能なOctaveスクリプトを記述する例は、Executable Octave Programsを参照してください。

Built-in Function: program_name ()

program_invocation_nameからリターンされた値(フルパス)の、最後の成分(ファイル名)をリターンします。

See also: program_invocation_name.

Built-in Function: program_invocation_name ()

Octaveを実行するためにシェルプロンプトにタイプされた名前をリターンします。

コマンドラインからスクリプトを実行した場合(例: octave foo.m)、あるいは実行可能なOctaveスクリプトを使用した場合、プログラム名はしのスクリプトの名前にセットされます。実行可能なOctaveスクリプトを作成する例は、Executable Octave Programsを参照してください。

See also: program_name.

以下は、これらの関数を使用して、Octaveを呼び出したコマンドラインを再現する例です

 
printf ("%s", program_name ());
arg_list = argv ();
for i = 1:nargin
  printf (" %s", arg_list{i});
endfor
printf ("\n");

セル配列からオブジェクトを取得する方法についての説明はIndexing Cell Arrays、変数narginについての情報はDefining Functionsを参照してください。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1.2 Startup Files

Octaveが開始されるとき、Octaveは以下のリストのファイルから、実行するコマンドを探します。これらのファイルには、関数定義を含む、任意の有効なOctaveコマンドが含まれるでしょう。

octave-home/share/octave/site/m/startup/octaverc

octave-homeはOctaveがインストールされたディレクトリーです(デフォルトは‘/usr/local’))。このファイルは、デフォルトのOctave環境にたいする変更を、そのサイトのすべてのユーザー、インストールされたOctaveのすべてのバージョンにたいして全体的に適用するために提供されています。このファイルへの変更は、そのサイトのOctaveユーザーすべてに影響を与えるため、注意を払うべきです。デフォルトファイルは、環境変数yによりオーバーライドされるかもしれません。

octave-home/share/octave/version/m/startup/octaverc

octave-homeはOctaveがインストールされたディレクトリー(デフォルトは‘/usr/local’)、versionはOctaveのバージョンナンバーです。このファイルは、特定のバージョンのOctaveを使用するすべてのユーザーにたいして、デフォルトのOctave環境への変更を全体的に適用するために提供されています。そのサイトで対象となるバージョンのOctaveを使用するすべてのユーザーに影響を与えるため、このファイルの変更には注意が払われるべきです。デフォルトファイルは環境変数OCTAVE_VERSION_INITFILEにより、オーバーライドされるかもしれません。

~/.octaverc

このファイルは、デフォルトOctave環境にたいして個人的に変更を行なうために使用されます。

.octaverc

このファイルは、特定のプロジェクトのデフォルトOctave環境にたいして変更を行なうために使用されます。Octaveは、‘~/.octaverc’を読み込んだ後に、カレントディレクトリーからこのファイルを検索します。‘~/.octaverc’ファイル内でのcdコマンドの使用は、Octaveが‘.octaverc’を検索するディレクトリーに影響を与えます。

ホームディレクトリーでOctaveを開始した場合、ファイル‘~/.octaverc’のコマンドは一度だけ実行されます。

--silent’オプションを指定せずに‘--verbose’オプションでOctaveを呼び出した場合、スタートアップファイルが読み込まれるたびに、メッセージが表示されます。

どのようなカスタマイズが可能で、どのカスタマイズが有効になっているかを決定するには、dump_prefs関数が便利です。

Function File: dump_prefs ()
Function File: dump_prefs (fid)

後からOctaveでパースできる形式で、現在のすべてのユーザープリファレンス変数をダンプします。fidfopenからリターンされたファイルディスクリプターです。fileが省略された場合、リストはstdoutにプリントされます。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.2 Quitting Octave

Built-in Function: exit (status)
Built-in Function: quit (status)

現在のOctaveセッションをexitします。オプションの整数値statusが与えられた場合、Octaveのexit statusとして、その値をオペレーティングシステムに渡します。デフォルト値は0です。

Built-in Function: atexit (fcn)
Built-in Function: atexit (fcn, flag)

Octaveをexitするときに呼び出される関数を登録します。たとえば、

 
function last_words ()
  disp ("Bye bye");
endfunction
atexit ("last_words");

これはOctaveをexitするとき、メッセージ"Bye bye"をプリントします。

追加の引数flagは、Octaveをexitするときに呼び出される関数のリストに、fcnを登録、または登録を取り消します。flagがtrueの場合、その関数は登録され、flagの場合は、その関数の登録が取り消されます。たとえば、上述の関数last_wordsを登録した後に

 
atexit ("last_words", false);

これはリストから関数を取り除くので、Octaveがexitするときlast_wordsは呼び出されません。

atexitはリストから最初の関数だけを取り除くことに注意してください。atexitによりリストに関数が複数ある場合は、同じように複数回取り除かなければなりません。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3 Commands for Getting Help

このマニュアルのテキスト全体は、Octaveプロンプトからdocコマンドを通じて利用できます。さらにユーザーが独自に記述した関数や変数のドキュメントも、helpコマンドを通じて利用できます。このセクションでは、マニュアルやユーザーが定義した関数や変数のドキュメント文字列を読むために使用するコマンドを説明します。作成した関数のドキュメント記述については、Function Filesを参照してください。

Command: help name
Command: help --list
Command: help .

nameにたいするヘルプテキストを表示します。たとえば、コマンドhelp helphelpコマンドを説明する短いメッセージをプリントします。

単一の引数--listが与えられた場合は、演算子、キーワード、ビルトイン関数、および現在のOctaveセッションで利用できるロード可能な関数を、すべてリストします。

単一も引数.が与えられた場合は、現在のOctaveセッションで利用できる、すべての演算子をリストします。

引数を指定せずに呼び出した場合、helpはコマンドラインからヘルプにアクセスする手順を表示します。

helpコマンドにより、コマンドの区切り文字に使用されるカンマとセミコロンを除いた、演算子の情報を得ることができます。それらについてのヘルプを得るには、help commahelp semicolonとタイプしなければなりません。

See also: doc, lookfor, which.

Command: doc function_name

GNU Infoブラウザを使用して、プリントされたマニュアルのオンラインバージョンから、関数function_nameのドキュメントを直接表示します。引数を指定せずに呼び出した場合、マニュアルの冒頭から表示されます。

たとえば、コマンドdoc randはマニュアルのオンラインバージョンのrandノードからGNU Infoブラウザを開始します。

GNU Infoブラウザが実行されると、コマンドC-hを使用して、使い方のヘルプを得ることができます。

See also: help.

Command: lookfor str
Command: lookfor -all str
Function File: [func, helpstring] = lookfor (str)
Function File: [func, helpstring] = lookfor ("-all", str)

現在の関数検索パスで見つかったすべての関数の中から、文字列strを検索します。デフォルトでは、lookforは見つかった関数それぞれのヘルプ文字列の最初のセンテンスからstrを検索します。引数"-all"が与えられた場合は、それぞれの関数のヘルプテキスト全体から検索します。検索はすべて大文字小文字を区別しません。

出力引数を指定せずに呼び出された場合、lookforはマッチした関数のリストを端末にプリントします。指定された場合、出力引数funcおよびhelpstringには、マッチした関数とその関数のヘルプ文字列の最初のセンテンスが定義されます。

最初のセンテンスを正しく認識するlookforの能力は、その関数のヘルプのフォーマットに依存します。Octaveの中心的な関数はすべて正しくフォーマットされていますが、外部パッケージとユーザー定義関数について同様に保証することはできません。したがって、Octaveの一部ではない、関連のある関数を見つけるために、"-all"引数の使用が必要になるかもしれません。

See also: help, doc, which.

Octaveのカレントリリースで何が新しくなったか確認するには、news関数を使用します。

Command: news
Command: news package

OctaveまたはインストールされたパッケージのカレントNEWSファイルを表示します。

引数を指定せずに呼び出した場合は、OctaveのNEWSファイルを表示します。パッケージ名packageが与えられた場合は、そのパッケージのカレントNEWSファイルを表示します。

Function File: info ()

GNU Octaveコミュニティーに連絡を取るための情報を表示します。

Built-in Function: warranty ()

Octaveを複製、および配布するための条件を説明します。

以下の関数は、ドキュメントを表示するために使用されるプログラムys,ドキュメントを探す場所を変更するために使用されます。

Built-in Function: val = info_file ()
Built-in Function: old_val = info_file (new_val)
Built-in Function: info_file (new_val, "local")

Octaveのinfoファイルの名前を指定する内部変数にたいして問い合わせ、またはセットをします。デフォルト値は‘octave-home/info/octave.info’です。octave-homeはOctaveをインストールしたルートディレクトリーです。デフォルト値は、環境変数OCTAVE_INFO_FILE、またはコマンドライン引数‘--info-file FNAME’によりオーバーライドされるかもしれません。

関数内から"local"と共に呼び出された場合、変数にたいする変更は、その関数と関数が呼び出すサブルーチンにたいしてローカルになります。その関数をexitするとき、変数の元の値がリストアされます。

See also: info_program, doc, help, makeinfo_program.

Built-in Function: val = info_program ()
Built-in Function: old_val = info_program (new_val)
Built-in Function: info_program (new_val, "local")

実行するinfoプログラムの名前を指定する内部変数の問い合わせ、またはセットを行います。デフォルト値は‘octave-home/libexec/octave/version/exec/arch/info’で、octave-homeはOctaveをインストールしたルートディレクトリー、versionはOctaveのバージョンナンバー、そしてarchはシステムタイプ(たとえばi686-pc-linux-gnu)です。デフォルト値は、環境変数OCTAVE_INFO_PROGRAM、またはコマンドライン引数‘--info-program NAME’でオーバーライドされるかもしれません。

関数の中から"local"オプションと共に呼び出された場合、変数への変更ははその関数および関数のサブルーチンにたいしてローカルになります。その関数をexitするときに、変数の元の値がリストアされます。

See also: info_file, doc, help, makeinfo_program.

Built-in Function: val = makeinfo_program ()
Built-in Function: old_val = makeinfo_program (new_val)
Built-in Function: makeinfo_program (new_val, "local")

Texinfoのマークアップコマンドを含むヘルプテキストをフォーマットするためにOctaveが実行するプログラム名を指定する内部変数にたいして、問い合わせまたはセットを行います。デフォルト値はmakeinfoです。

関数の中から"local"オプションと共に呼び出された場合、その変数にたいする変更は、その関数および関数のサブルーチンにたいしてローカルになります。関数をexitするときに、変数の元の値がリストアされます。

See also: texi_macros_file, info_file, info_program, doc, help.

Built-in Function: val = texi_macros_file ()
Built-in Function: old_val = texi_macros_file (new_val)
Built-in Function: texi_macros_file (new_val, "local")

ドキュメント文字列がmakeinfoに渡される前に、文字列の前に追加されるTexinfoマクロを含むファイルの名前を指定する内部変数にたいして、問い合わせまたはセットを行います。デフォルト値は‘octave-home/share/octave/version/etc/macros.texi’です。ここで、octave-homeはOctaveをインストールしたルートディレクトリー、versionはOctaveのバージョンナンバーです。デフォルト値は、環境変数OCTAVE_TEXI_MACROS_FILE、またはコマンドライン引数‘--texi-macros-file FNAME’により、オーバーライドされるかもしれません。

関数の中から"local"オプションと共に呼び出された場合、変数への変更は、その関数または関数のサブルーチンにたいしてローカルになります。関数をexitするときに、変数の元の値がリストアされます。

See also: makeinfo_program.

Built-in Function: val = doc_cache_file ()
Built-in Function: old_val = doc_cache_file (new_val)
Built-in Function: doc_cache_file (new_val, "local")

Octaveのドキュメントキャッシュファイルの名前を指定する内部変数にたいして、問い合わせ、またはセットを行います。キャッシュファイルは、lookforコマンドはパフォーマンスを大幅に改善します。デフォルト値は‘octave-home/share/octave/version/etc/doc-cache’です。ここで、octave-homeはOctaveをインストールしたルートディレクトリー、versionはOctaveのバージョンナンバーです。デフォルト値は、環境変数OCTAVE_DOC_CACHE_FILE、またはコマンドライン引数‘--doc-cache-file FNAME’によりオーバーライドされるかもしれません。

関数の中から"local"オプションと共に呼び出された場合、変数への変更は、その関数または関数のサブルーチンにたいしてローカルになります。関数をexitするとき、変数の元の値がリストアされます。

See also: doc_cache_create, lookfor, info_program, doc, help, makeinfo_program.

Built-in Function: val = built_in_docstrings_file ()
Built-in Function: old_val = built_in_docstrings_file (new_val)
Built-in Function: built_in_docstrings_file (new_val, "local")

Octaveのビルトイン関数のdocstringを含むファイルの名前を指定する内部変数にたいして、問い合わせまたはセットを行います。デフォルト値は‘octave-home/share/octave/version/etc/built-in-docstrings’です。ここで、octave-homeはOctaveをインストールしたルートディレクトリー、versionはOctaveのバージョンナンバーです。デフォルト値は、環境変数OCTAVE_BUILT_IN_DOCSTRINGS_FILE、またはコマンドライン引数‘--built-in-docstrings-file FNAME’によりオーバーライドされるかもしれません。

注意: この変数はOctave自身の初期化時だけ使用されます。Octaveセッション実行中に変更しても、Octaveに影響しません。

Built-in Function: val = suppress_verbose_help_message ()
Built-in Function: old_val = suppress_verbose_help_message (new_val)
Built-in Function: suppress_verbose_help_message (new_val, "local")

helpコマンドの出力とビルトイン関数の使い方メッセージのの最後に、Octaveが付加的なヘルプ情報を追加するかどうかと、を制御する内部変数にたいして、問い合わせまたはセットを行います。

関数の中から"local"オプションと共に呼び出された場合、変数の変更は、その関数または関数のサブルーチンにたいしてローカルになります。関数をexitするときに、元の変数の値がリストアされます。

以下の関数は、ドキュメントを生成するために、主にOctaveにより内部的に使用されます。これらの関数は、ユーザーにとって便利なときがあるかもしれないので、ここに完全なドキュメントを示します。

Function File: doc_cache_create (out_file, directory)

与えられたディレクトリー内のすべての関数にたいするドキュメントキャッシュを生成します。

directory内のすべての関数にたいするドキュメントキャッシュを生成します。生成されたキャッシュは、ファイルout_fileに保存されます。このキャッシュは、lookforのスピードアップのために使用されます。

ディレクトリーが与えられない(または空のマトリクスが与えられた)場合は、ビルトイン演算子などにたいするキャッシュが生成されます。

See also: doc_cache_file, lookfor, path.

Built-in Function: [text, format] = get_help_text (name)

関数nameのrawヘルプテキストをリターンします。

textにrawヘルプテキスト、formatのフォーマットがリターンされます。フォーマットは文字列で、"texinfo""html""plain text"のうちの1つです。

Built-in Function: [text, format] = get_help_text_from_file (fname)

ファイルfnameのrawヘルプテキストをリターンします。

textにrawヘルプテキスト、formatのフォーマットがリターンされます。フォーマットは文字列で、"texinfo""html""plain text"のうちの1つです。

Function File: [text, status] = get_first_help_sentence (name)
Function File: [text, status] = get_first_help_sentence (name, max_len)

関数のヘルプテキストの最初のセンテンスをリターンします。

最初のセンテンスとは、関数定義の後ろから、最初のピリオド(".")、または連続する改行("\n\n")までのテキストです。テキストは最大長max_len(デフォルトは80)に切り詰められます。

オプションの出力引数statusには、makeinfoかr報告されたステータスがリターンされます。要求される出力引数が1つで、statusが非0の場合は警告が表示されます。

例として、この関数のヘルプテキストの最初のセンテンスは、以下のようになります

 
get_first_help_sentence ("get_first_help_sentence")
-| ans = Return the first sentence of a function's help text.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4 Command Line Editing

Octaveは、豊富なコマンドライン編集とヒストリー機能を提供するために、GNU Readlineライブラリーを使用しています。このマニュアルでは、もっとも一般的な機能についてだけ説明します。さらに、すべての編集コマンドは、ユーザーにより自由に別のキーストロークのバインドできます。このマニュアルでは、Emacsのデフォルトのキーバインディングを変更していない前提で説明します。Readlineのカスタマイズと、完全な機能については、GNU Readlineのマニュアルを参照してください。

印字可能文字(文字、数字、シンボルなど)の挿入は、単にその文字をタイプするだけです。Octaveはカーソル位置に文字を挿入して、カーソルを前方に進めます。

コマンドライン編集関数の操作の多くは、コントロール文字を使用します。たとえば文字Control-aは、カーソルをその行の先頭に移動します。C-aのタイプは、<CTRL>を押したまま、<a>を押します。以降のセクションでは、Control-aのようなコントロール文字は、C-aと表記します。

メタ文字を使用するコマンドライン編集関数もあります。M-uをタイプするには、<META>キーを押したまま、<u>を押します。キーボードによっては、<META>が<ALT>とラベルされていたり、<WINDOWS>とラベルされていることさえあります。端末に<META>がない場合でも、ESCで始まる2文字シーケンスを使ってメタ文字を入力できます。この場合M-uを入力するには、<ESC>の次に<u>をタイプします。実際のMetaキーがある端末でも、ESC文字シーケンスは利用できます。以降のセクションでは、Meta-uのようなメタ文字は、M-uのように表記します。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4.1 Cursor Motion

以下のコマンドで、カーソルを動かすことができます。

C-b

1文字後退します。

C-f

1文字前進します。

<BACKSPACE>

カーソルの左の文字を削除します。

<DEL>

カーソルの下の文字を削除します。

C-d

カーソルの下の文字を削除します。

M-f

1単語前方に移動します。

M-b

1単語後方に移動します。

C-a

行の先頭に移動します。

C-e

行の末尾に移動します。

C-l

スクリーンをクリアーして、カレント行をスクリーンのトップに再印字します。

C-_
C-/

最後の操作をアンドゥします。すべてをアンドゥして空の行まで戻ることができます。

M-r

その行へのすべての変更をアンドゥします。これは最初に戻るまで充分な回数だけ‘undo’コマンドをタイプするのと同様です。

上記のテーブルでは、入力行で編集を行うのに必要となる、もっとも基本的な利用できるキーストロークを説明しています。ほとんどの端末では、C-fC-bで前方または後方へ移動するのに、左矢印キーと右矢印キーも利用できます。

C-fは1文字前方、M-fは1単語前方へ移動する点に注目してください。コントロールによるキーストロークは文字単位の処理、メタによるキーストロークは単語単位の処理という、緩い慣習があります。

関数clcにとり、実行中のOctaveプログラム内のスクリーンをクリアーできます。

Built-in Function: clc ()
Built-in Function: home ()

端末スクリーンをクリアーして、カーソルを左上隅に移動します。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4.2 Killing and Yanking

テキストをキルするとは、行からテキストを削除しますが、後でそれを使用する(通常はヤンクにより行に戻す)ために、それを保存するという意味です。コマンドの説明で、そのコマンドがテキストを‘キル’する、と記述されているときは、後から違う(または同じ)場所に戻せることが保証されます。

以下はテキストをキルするコマンドのリストです。

C-k

現在のカーソル位置から行末までのテキストをキルします。

M-d

カーソルから現在の単語の末尾まで、カーソルが単語と単語の間にある場合は次の単語の末尾までをキルします。

M-<DEL>

カーソルから現在の単語の先頭まで、カーソルが単語と単語の間にある場合は前の単語の先頭までをキルします。

C-w

カーソルから前の空白までをキルします。単語境界が違うので、M-<DEL>とは異なります。

以下は、その行にテキストをyankで戻す方法です。ヤンクとは、kキルバッファーからもっとも最近キルされたテキストをコピーするという意味です。

C-y

そのバッファーのカーソル位置に、もっとも最近キルされたテキストをヤンクして戻します。

M-y

キルリンクをローテートして、新たなトップをヤンクします。直前のコマンドがC-yまたはM-yのときだけ、これを行なうことができます。

キルコマンドを使うと、そのテキストはキルリング(kill-ring)に保存されます。任意の回数の連続したキルコマンドは、キルされたすべてのテキストを1つにまとめるので、それをヤンクで戻すときは、一度にまとめてヤンクできます。キルリングは特定の行に限定されたものではありません。以前にタイプしたラインでキルしたテキストは、後で他の行をタイプしているときに、ヤンクで戻すことができます。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4.3 Commands For Changing Text

以降のコマンドは、他の場合では特別な意味をもつ文字(例: <TAB>、C-qなど)を入力したり、タイプミスをすばやく訂正するために使用できます。

C-q
C-v

次にタイプする文字そのものを、行に追加します。これは、C-qのような文字を挿入する方法の一例です。

M-<TAB>

Insert a tab character.

C-t

カーソルのある文字の前方にカーソルの前の文字をドラッグするとともに、カーソルを進めます。カーソルが行の末尾にある場合は、カーソルの前の2文字を入れ換えます。

M-t

同様に、カーソルの前方の単語をカーソルの後方へドラッグして、カーソルの後方にあった単語の前方にカーソルを移動します。

M-u

現在の単語(または次の単語からの)の末尾までを大文字にして、その単語の末尾にカーソルを移動します。

M-l

現在の単語(または次の単語からの)の末尾までを小文字にして、その単語の末尾にカーソルを移動します。

M-c

カーソルの前方(カーソルが単語と単語の間にある場合は次の単語の先頭)を大文字にして、その単語の末尾にカーソルを移動します。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4.4 Letting Readline Type For You

以降のコマンドにより、コマンドや変数の名前をOctaveに補完させることができます。

<TAB>

カーソルの前のテキストにたいして補完を試みます。Octaveはコマンドと変数の名前を補完することができます。

M-?

カーソルの前のテキストにたいして、可能な補完をリストします。

Built-in Function: val = completion_append_char ()
Built-in Function: old_val = completion_append_char (new_val)
Built-in Function: completion_append_char (new_val, "local")

コマンドラインの成功した補完に追加する文字のための内部変数にたいして、問い合わせまたはセットを行います。デフォルト値は" "(スペース1つ)です。

関数の中から"local"オプションと共に呼び出された場合、変数の変更は、その関数または関数のサブルーチンにたいしてローカルになります。関数をexitするときに、元の変数の値がリストアされます。

Built-in Function: completion_matches (hint)

与えられたhintにたいして、可能な補完を生成します。

この関数は、Octaveを制御したりユーザー入力を処理するEmacsのようなプログラムのために提供されています。この関数が呼び出されても、カレントコマンドナンバーはインクリメントされません。これはバグではなく仕様です。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4.5 Commands For Manipulating The History

Octaveは通常、以前にタイプされたコマンドうぃ編集や再実行できるように、タイプしたコマンドを記録しています。Octaveをexitするとき、もっとも最近タイプされたコマンドから、変数history_sizeで指定された個数までのコマンドがファイルに保存されます。Octaveが開始されるとき、変数history_fileの名前のファイルから、コマンドの初期リストがロードされます。

以下は、ヒストリーリストを簡単に閲覧したり、検索するためのコマンドです。

<LFD>
<RET>

カーソルの位置に関わらず、カレント行を受け入れます。その行が空でない場合は、その行をヒストリーに加えます。その行がヒストリー行だった場合は、ヒストリー行を元の状態にリストアします。

C-p

ヒストリーリストを‘上’に移動します。

C-n

ヒストリーリストを‘下’に移動します。

M-<

ヒストリーリストの最初の行に移動します。

M->

入力ヒストリーの最後の行(あなたが入力している行です!)に移動します。

C-r

カレント行から後方検索を開始して、必要ならヒストリーを‘上’に移動します。これはインクリメンタル検索です。

C-s

カレント行から前方検索を開始して、必要ならヒストリーを‘下’に移動します。

多くの端末では、ヒストリーリストを移動するのに、C-pC-nのかわりに上矢印キーと下矢印キーを使用できます。

ヒストリーリストを移動するコマンドに加えて、Octaveはヒストリーリストからコマンド群を閲覧、編集、再実行するために3つの関数を提供します。

Command: history
Command: history opt1
Built-in Function: h = history ()
Built-in Function: h = history (opt1, …)

引数を指定せずに呼び出すと、historyは実行されたコマンドのリストを表示します。有効なオプションは:

n
-n

ヒストリーリストのもっとも最近のn行だけを表示します。

-c

ヒストリーリストをクリアーします。

-q

表示されるヒストリーリストの番号を表示しません。これは、X Window Systemを使用してカットアンドペーストを行なうときに便利です。

-r file

ファイルfileを読み込んで、その内容をカレントヒストリーリストに追加します。名前が省略された場合はデフォルトのヒストリーファイル(通常は‘~/.octave_hist’)を使用します。

-w file

カレントヒストリーを、ファイルfileに書き込みます。名前が省略された場合はデフォルトのヒストリーファイル(通常は‘~/.octave_hist’)を使用します。

たとえば、もっとも最近タイプされたコマンド5つを、行番号なしで表示するには、コマンドhistory -q 5を使用します。

出力引数が1つで呼び出された場合、ヒストリーはその引数のセル文字列として保存され、スクリーンに表示されません。

Command: edit_history
Command: edit_history cmd_number
Command: edit_history first last

変数EDITORで指定された名前のエディターを使って、ヒストリーリストを編集します。

編集されるコマンドは、最初にテンポラリーファイルにコピーされます。エディターをexitするとき、Octaveはそのファイル内に残ったコマンドを実行します。関数を定義するとき、それを直接コマンドラインに入力するのではなく、edit_historyを使うほうが便利なときがあります。そのコマンドブロックは、エディターをexitするとすぐに実行されます。コマンドを実行したくないときは、エディターを抜けるときに、単にそのバッファーのすべての行を削除してください。

引数なしで呼び出された場合は、以前に実行されたコマンドを編集します。引数が1つの場合は、指定されたコマンドcmd_numberを編集します。引数が2つの場合は、firstlastの間のコマンドを編集します。コマンド番号には、負の数も指定できます。この場合、-1はもっとも最近実行されたコマンドを参照します。以下のコマンドは等価で、どちらももっとも最近実行されたコマンドを編集します。

 
edit_history
edit_history -1

範囲を使用する場合、最初のコマンドに最後のコマンドより大きい番号を指定すると、編集されるバッファーに配置される前に、コマンドリストを逆転します。

See also: run_history.

Command: run_history
Command: run_history cmd_number
Command: run_history first last

ヒストリーリストからコマンドを実行します。

引数なしで呼び出された場合は、以前に実行されたコマンドを実行します。引数が1つの場合は、指定されたコマンドcmd_numberを実行します。引数が2つの場合は、firstlastの間のコマンドを実行します。コマンド番号には、負の数も指定できます。この場合、-1はもっとも最近実行されたコマンドを参照します。以下のコマンドは等価で、どちらももっとも最近実行されたコマンドを編集します。たとえば以下のコマンド

 
run_history
     OR
run_history -1

はもっとも最近のコマンドを再実行します。また、

 
run_history 13 169

は13から169のコマンドを実行します。

最初のコマンドに最後のコマンドより大きい番号を指定すると、編集されるバッファーに配置される前に、コマンドリストを逆転します。たとえば:

 
disp (1)
disp (2)
run_history -1 -2
⇒
 2
 1

See also: edit_history.

Octaveでは、ヒストリーがいつ、どこで、どのように保存されたかの詳細もカスタマイズできます。

Built-in Function: val = history_save ()
Built-in Function: old_val = history_save (new_val)
Built-in Function: history_save (new_val, "local")

ヒストリーファイルに、コマンドがコマンドラインから入力されたかどうかを保存するか制御する内部変数にたいして、問い合わせまたはセットを行います。

関数内から"local"オプションと共に呼び出された場合、変数の変更はその関数および関数のサブルーチンにたいしてローカルになります。その関数をexitするとき、変数の元の値がリストアされます。

See also: history_control, history_file, history_size, history_timestamp_format_string.

Built-in Function: val = history_control ()
Built-in Function: old_val = history_control (new_val)

コマンドがヒストリーリストに保存される方法を指定する内部変数にたいして、問い合わせまたはセットを行います。デフォルト値は空文字列ですが、環境変数OCTAVE_HISTCONTROLによりオーバーライドされるかもしれません。

history_controlの値は、コマンドをヒストリーリストに保存する方法を制御する、コロンで区切られた値です。値リストがignorespaceを含む場合、スペース文字で始まる行は、ヒストリーリストに保存されません。ignoredupsでは、以前のヒストリーにマッチする行はヒストリーに保存されません。値ignorebothは、ignorespaceignoredupsの省略指定です。値erasedupsは、カレント行がヒストリーリストに保存される前に、ヒストリーリストからマッチするすべての行を削除します。上記のリスト以外の値はすべて無視されます。history_controlが空文字列の場合、すべてのコマンドはhistory_saveの値として、すべてヒストリーリストに保存されます。

See also: history_file, history_size, history_timestamp_format_string, history_save.

Built-in Function: val = history_file ()
Built-in Function: old_val = history_file (new_val)

コマンドヒストリーを保存するのに使用するファイルの名前を指定する内部変数にたいして、問い合わせまたはセットを行います。デフォルト値は‘~/.octave_hist’ですが、環境変数OCTAVE_HISTFILEによりオーバーライドされるかもしれません。

See also: history_size, history_save, history_timestamp_format_string.

Built-in Function: val = history_size ()
Built-in Function: old_val = history_size (new_val)

ヒストリーファイルに保存するエントリー数を指定する内部変数にたいして、問い合わせまたはセットを行います。デフォルト値は1000ですが、環境変数OCTAVE_HISTSIZEによりオーバーライドされるかもしれません。

See also: history_file, history_timestamp_format_string, history_save.

Built-in Function: val = history_timestamp_format_string ()
Built-in Function: old_val = history_timestamp_format_string (new_val)
Built-in Function: history_timestamp_format_string (new_val, "local")

Octaveをexitするときにヒストリーファイルに書き込まれるコマンドラインにたいするフォーマット文字列を指定する内部変数にたいして、問い合わせまたはセットを行います。このフォーマット文字列はstrftimeに渡されます。デフォルト値は

 
"# Octave VERSION, %a %b %d %H:%M:%S %Y %Z <USER@HOST>"

関数内から"local"オプションと共に呼び出された場合、変数の変更はその関数または関数のサブルーチンにたいしてローカルになります。関数をexitするときに、変数の元の値がリストアされます。

See also: strftime, history_file, history_size, history_save.

Built-in Function: val = EDITOR ()
Built-in Function: old_val = EDITOR (new_val)
Built-in Function: EDITOR (new_val, "local")

デフォルトのテキストエディターを指定する内部変数にたいして、問い合わせまたはセットを行います。

デフォルト値はOctave開始時に環境変数EDITORから取得されます。環境変数が初期化されない場合、EDITOR"emacs"にセットされます。

関数の中から"local"オプションと共に呼び出された場合、変数の変更は、その関数または関数のサブルーチンにたいしてローカルになります。関数をexitするときに、元の変数の値がリストアされます。

See also: edit, edit_history.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4.6 Customizing readline

Octaveはコマンドライン変数およびヒストリー機能のために、GNU Readlineライブラリーを使用しています。Readlineはとてもフレキシブルで、コマンドの設定ファイルを通じてカスタマイズできます(正確なコマンド構文についてはGNU Readlineライブラリーを参照してください)。デフォルトの設定ファイルは通常、‘~/.inputrc’です。

OctaveはReadlineを初期化するためのコマンドを提供しており、それによりコマンドラインの挙動を変更できます。

Built-in Function: readline_read_init_file (file)

readline初期化ファイルfileを読み込みます。fileが省略された場合には、デフォルトの初期化ファイル(通常は‘~/.inputrc’)を読み込みます。

詳細は(readline)Readline Init File section ‘Readline Init File’ in GNU Readline Libraryを参照してください。

See also: readline_re_read_init_file.

Built-in Function: readline_re_read_init_file ()

最後に読み込んだreadline初期化ファイルを再読込します。詳細は (readline)Readline Init File section ‘Readline Init File’ in GNU Readline Libraryを参照してください。

See also: readline_read_init_file.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4.7 Customizing the Prompt

以降の変数による、コマンドラインプロンプトの外観をカスタマイズできます。Octaveでは、バックスラッシュでエスケープされたいくつかの特別な文字を挿入することにより、プロンプトをカスタマイズできます。それらの文字は以下のようにデコードされます:

\t

時刻。

\d

日付。

\n

改行と復帰と等価なものをプリントすることにより、新たな行を開始します。

\s

プログラムの名前(通常は単に‘octave’)です。

\w

カレントワーキングディレクトリー。

\W

カレントワーキングディレクトリーのbasename。

\u

カレントユーザーのユーザー名。

\h

最初の‘.’までのhostname。

\H

hostname。

\#

Octave起動後からカウントした、そのコマンドのコマンド番号。

\!

そのコマンドのヒストリー番号。これはOctave開始時からのヒストリーリスト内のコマンド数なので、‘\#’とは異なります。

\$

実行UIDが0のときは‘#’、それ以外は‘$’。

\nnn

文字コードが8進nnnの文字。

\\

バックスラッシュ。

Built-in Function: val = PS1 ()
Built-in Function: old_val = PS1 (new_val)
Built-in Function: PS1 (new_val, "local")

一次プロンプト(primary prompt)文字列にたいして、問い合わせまたはセットを行います。インタラクティブに実行された場合は、コマンドを読み取る準備ができたときに、Octaveは一次プロンプトを表示します。

一次プロンプト文字列のデフォルト値は"octave:#> "です。これを変更するには、以下のようなコマンドを使用します。

 
PS1 ("\\u@\\H> ")

これは、ホスト‘kremvax.kgb.su’にログインしているユーザー‘boris’のプロンプトを、‘boris@kremvax> ’にします。ダブルクォートされた文字列内にバックスラッシュを入力するには、バックスラッシュが2つ必要なことに注意してください。Stringsを参照してください。

端末がサポートしていれば、ANSIエスケープシーケンスも使用できます。これはプロンプトにカラーを使いたいとき便利かもしれません。たとえば、

 
PS1 ("\\[\\033[01;31m\\]\\s:\\#> \\[\\033[0m\\]")

これはデフォルトのOctaveプロンプトのカラーを赤にします。

関数の中から"local"オプションと共に呼び出された場合、変数の変更はその関数または関数のサブルーチンにたいしてローカルになります。関数をexitするときに、変数の元の値がリストアされます。

See also: PS2, PS4.

Built-in Function: val = PS2 ()
Built-in Function: old_val = PS2 (new_val)
Built-in Function: PS2 (new_val, "local")

二次プロンプト文字列にたいして、問い合わせまたはセットを行います。二次プロンプトは、Octaveがコマンドを完成させるために、追加入力を待っているときにプリントされます。たとえば、複数行に分かれたforループをタイプしているとき、Octaveは最初の行以降の各行の先頭に二次プロンプトをプリントするでしょう。二次プロンプト文字列のデフォルト値は、"> "です。

関数の中から"local"オプションと共に呼び出された場合、変数の変更はその関数または関数のサブルーチンにたいしてローカルになります。関数をexitするときに、元の変数の値がリストアされます。

See also: PS1, PS4.

Built-in Function: val = PS4 ()
Built-in Function: old_val = PS4 (new_val)
Built-in Function: PS4 (new_val, "local")

コマンドのエコーが有効なときに、生成された出力のプレフィクスに使用する文字列の、問い合わせまたはセットを行います。デフォルト値は"+ "です。コマンドのエコーについての説明は、Diary and Echo Commandsを参照してください。

関数の中から"local"オプションと共に呼び出された場合、変数の変更はその関数または関数のサブルーチンにたいしてローカルになります。関数をexitするときに、変数の元の値がリストアされます。

See also: echo, echo_executing_commands, PS1, PS2.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4.8 Diary and Echo Commands

Octaveのダイアリー機能により、インタラクティブなセッションのすべて、または一部のログを維持できます。これは、タイプされた入力と、Octaveが生成した出力を、別のファイルに記録することにより行なわれます。

Command: diary
Command: diary on
Command: diary off
Command: diary filename

すべてのコマンドのリストおよびそれらが生成した出力を、まさに端末に表示されたよyに混在して記録します。

有効なオプションは:

on

カレントワーキングディレクトリーの‘diary’と呼ばれるファイルへ、セッションの記録を開始します。

off

ダイアリーファイルへのセッションの記録を停止します。

filename

filenameという名前のファイルに、セッションを記録します。

引数を指定しない場合、カレントダイアリーの状態うぃ切り替えます。

See also: history.

関数やスクリプトが評価されるときに、それらの中のコマンドを確認できると便利な場合があります。これは、ある種の問題をデバッグするとき、特に助けになるでしょう。

Command: echo options

コマンドが評価されるときに、それらのコマンドを表示するかどうかを制御します。有効なオプションは:

on

スクリプトファイル内でコマンドが実行されるとき、エコーを有効にします。

off

スクリプトファイル内でコマンドが実行されるとき、エコーを無効にします。

on all

スクリプトファイルおよび関数内でコマンドが実行されるとき、エコーを有効にします。

off all

スクリプトファイルおよび関数内でコマンドが実行されるとき、エコーを無効にします。

引数を指定しない場合、echoはエコー状態を切り替えます。

Built-in Function: val = echo_executing_commands ()
Built-in Function: old_val = echo_executing_commands (new_val)
Built-in Function: echo_executing_commands (new_val, "local")

エコー状態を制御する内部変数にたいして、問い合わせまたはセットを行います。値は以下の値の和になるでしょう:

1

スクリプトファイルから読み込んだコマンドをエコーします。

2

関数のコマンドをエコーします。

4

コマンドラインから読み込んだコマンドをエコーします。

一度に2つ以上の状態がアクティブになり得ます。たとえば、値3は、コマンドecho on allと等価です。

echo_executing_commandsの値は、echoコマンドまたはコマンドラインオプション‘--echo-commands’によりセットされるかもしれません。

関数の中から"local"オプションと共に呼び出された場合、変数の変更は、その関数または関数のサブルーチンにたいしてローカルになります。関数をexitするときに、元の変数の値がリストアされます。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.5 How Octave Reports Errors

Octaveは無効なプログラムにたいして、2つの種類のエラーをリポートします。

パースエラーは、Octaveがタイプされたものを理解できなかった場合に発生します。たとえば、キーワードのスペルミスをした場合、

 
octave:13> function y = f (x) y = x***2; endfunction

Octaveは即座に次のようなメッセージを返すでしょう:

 
parse error:

  syntax error

>>> function y = f (x) y = x***2; endfunction
                              ^

多くのパースエラーにたいして、Octaveは入力行で理解できなかった箇所をマークするのに、キャレット(‘^’)を使用します。上記のケースでは、べき乗(**)にたいするキーワードにスペルミスがあるので、Octaveはエラーメッセージを生成しました。キャレットは3つ目の‘*’にエラーをマークしました。なぜなら、その箇所まではコードは正しく読み取れていたけれど、最後の‘*’が理解できなかったからです。

他のクラスのエラーメッセージは、評価時に発生します。これらのエラーは、ランタイムエラーまたは, 評価エラーと呼ばれることもあります。これは、それらのエラーが、プログラムが実行(run)あるいは評価(evaluate)されるときに発生するからです。たとえば、前の関数定義のミスを訂正したあとで、以下をタイプしたとします

 
octave:13> f ()

Octaveは以下のように応答するでしょう

 
error: `x' undefined near line 1 column 24
error: called from:
error:   f at line 1, column 22

このエラーメッセージにはいくつかのパートがあります。そして、それらはエラーのあるソースを見つける助けとなる情報を多く含んでいます。このメッセージは、最内のエラー箇所から生成され、それを囲む式と関数呼び出しのバックトレースを提供します。

上記の例の最初の行は、何らかの関数または式の、行1、列24の近くで、名前‘x’の未定義な変数が見つかったことを示しています。関数内で発生したエラーにたいしては、行はその関数定義を含むファイルの先頭から数えた行のことです。関数の外側で発生したエラーにたいしては、行番号は入力行番号であり、これは通常一次プロンプト文字列に表示されています。

エラーメッセージの2行目と3行目は、このエラーが関数fの中で発生したことを示しています。もし関数fがさらに他の関数、たとえばgから呼び出されていた場合には、エラーリストにはさらに以下のような1行が加わるでしょう:

 
error:   g at line 1, column 17

これらの関数呼び出しのリストは、エラーが発生するまでにそのプログラムがとったパスのトレースと、プログラムを再試行する前にエラーを訂正するのを、とても簡単にします。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.6 Executable Octave Programs

一度Octaveを習得したら、‘#!’スクリプトメカニズムを使ってOctaveによる自己完結型スクリプトを記述したいと思うかもしれません。これはGNUシステム、および多くのUnixシステム(1)で行なうことができます。

Octave自己完結型スクリプトは、Octave言語で記述されたプログラムに関する知識を要さずに、ユーザーが呼び出せるプログラムを記述したいときに便利です。Octaveスクリプトは、データファイルのバッチプロセッシングにも使用されます。一度アルゴリズムが開発され、Octaveのインタラクティブ環境でテストされれば、それを実行可能スクリプトにコミットして、データファイルに何度も使用できます。

実行可能Octaveスクリプトの些細な例として、あなたは以下の行を含む‘hello’という例の名前のファイルを作るかもしれません:

 
#! octave-interpreter-name -qf
# a sample Octave program
printf ("Hello, world!\n");

(octave-interpreter-nameはOctaveバイナリーのフルパスで置き換えてください)。スクリプトはファイルの先頭に‘#!’があるときだけ機能することに注意してください。(Unixシステムではchmodで)ファイルを実行可能にした後は、以下のようにシェル上で単にタイプできます:

 
hello

システムはあなたがタイプしたものを以下のようにアレンジして、Octaveを実行します:

 
octave hello

#!’で始まる行は、実行されるインタープリターのファイル名へのフルパスと、そのインタープリターに渡す初期化のためのオプションのコマンドライン引数です。するとオペレーティングシステムは与えられた引数と、実行されるプログラムの完全な引数リストにより、インタープリターを実行します。リストの最初の引数は、実行可能なOctaveのフルパスファイル名です。引数リストの残りはOctaveへのオプション、データファイル、またはその両方です。‘-qf’オプションは通常、スタンドアローンなOctaveプログラム内での、通常のスタートアップメッセージのプリントを抑止して、特定のユーザーの‘~/.octaverc’の内容に依存した異なる挙動から守ります。Invoking Octave from the Command Lineを参照してください。

#!’の後ろの文字数に制限のあるオペレーティングシステムがいくつかあることに注意してください。また、‘#!’の行内の引数のパースは、さまざまなシェルやシステムにより異なります。これらの多くは、すべての引数を1つの文字列にまとめて、インタープリターに1つの引数として渡します。この場合、以下のスクリプト:

 
#! octave-interpreter-name -q -f # comment

は、コマンドラインで以下のようにタイプするのと等価です:

 
octave "-q -f # comment"

そして、これはエラーになるでしょう。残念ながら、コマンドラインから呼び出されたのか、それとも‘#!’スクリプトから呼び出されたかを、Octaveが判断するのは不可能です。したがって、‘#!’メカニズムを使用するときは、いくつかの配慮が必要です。

Octaveが実行可能スクリプトから起動された場合、ビルトイン関数argvはスクリプトの‘#!’行でOctaveインタープリターに渡された引数ではなく、実行可能Octaveスクリプトに渡されたコマンドライン引数を含むセル配列をリターンします。たとえば、以下のプログラムは‘-qf’ではなく、スクリプトを実行するために使用されたコマンドライン引数を再現します。

 
#! /bin/octave -qf
printf ("%s", program_name ());
arg_list = argv ();
for i = 1:nargin
  printf (" %s", arg_list{i});
endfor
printf ("\n");

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.7 Comments in Octave Programs

コメントとは、人間の読み手のためにプログラム中に含まれるテキストのことで、このテキストはプログラムの実行パートではありません。コメントにより、そのプログラムが何を行なうか、どのように機能するか説明することができます。ほとんどすべてのプログラミング言語にはコメントにたいする規約があります。なぜならプログラムは通常、コメントがなければ理解するのが困難だからです。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.7.1 Single Line Comments

Octave言語では、コメントはシャープ記号‘#’、あるいはパーセント記号‘%’のどちらかで始まり、その行の末尾までがコメントになります。シャープ記号またはパーセント記号に続く任意のテキストは、Octaveインタープリターには無視され、実行されません。以下の例では、行全体のコメントと、行の一部を使用したコメントが使用されています。

 
function countdown
  # Count down for main rocket engines 
  disp (3);
  disp (2);
  disp (1);
  disp ("Blast Off!");  # Rocket leaves pad
endfunction

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.7.2 Block Comments

マッチする‘#{’と‘#}’、または‘%{’と‘%}’で囲むことにより、コードブロック全体をコメント化することができます。たとえば、

 
function quick_countdown
  # Count down for main rocket engines 
  disp (3);
 #{
  disp (2);
  disp (1);
 #}
  disp ("Blast Off!");  # Rocket leaves pad
endfunction

これは、"disp (2);"と"disp (1);"を実行しないことにより、'3'から"Blast Off"へのとても素早いカウントダウンを生成します。

ブロックコメントマーカーは、正しくパースされるために、その行で(空白文字以外の)単独の文字として記述しなければなりません。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.7.3 Comments and the Help System

helpコマンド(Commands for Getting Help参照)は、関数の最初のコメントブロックを見つけて、それらをドキュメント文字列としてリターンします。これはヘルプを取得するために使用する同じコマンドが、ユーザー定義関数を正しくフォーマットできることを意味します。たとえば、以下の関数fを定義してみます

 
function xdot = f (x, t)

# usage: f (x, t)
#
# This function defines the right-hand
# side functions for a set of nonlinear
# differential equations.

  r = 0.25;
  …
endfunction

すると、コマンドhelp fは以下の出力を生成します

 
 usage: f (x, t)

 This function defines the right-hand
 side functions for a set of nonlinear
 differential equations.

キーボード入力して使い捨てするプログラムにコメント行を挿入することはできますが、これは通常とても有用とは言えません。なぜならコメントの目的は、後で他の人がプログラムを理解する助けとなることだからです。

helpパーサーは、初期ヘルプテキストとして、1行コメント(Single Line Comments参照)だけを正しく認識します。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3. Data Types

Octaveのすべてのバージョンにはいくつかのビルトインデータ型が含まれます。それらには、real(実数)およびcomplex(複素数)にたいするスカラー(scalar)とマトリクス(matrix)、文字列(character string)、データ構造型(data structure type)、そしてすべてのデータ型を含むことができる配列(array)が含まれます。

少しC++コードを記述すれば、新しく特別なデータ型を定義することもできます。Octave実行中に新しいデータ型をダイナミック(動的)にロードできるシステムもいくつかあり、その場合はOctaveすべてをリコンパイルせずに、新しいデータ型を単に追加できます。Octaveのダイナミックリンク能力についての情報は、External Code Interfaceを参照してください。User-defined Data Typesでは、Octaveに新しいデータ型を定義するために、何を行わなければならないか説明しています。

Built-in Function: typeinfo ()
Built-in Function: typeinfo (expr)

exprの型を、文字列でリターンします。exprが省略された場合は、現在インストールされているデータ型すべてを含む文字列のセル配列をリターンします。

See also: class, isa.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1 Built-in Data Types

標準のビルトインデータ型は、real(実数)およびcomplex(複素数)のスカラー(scalar)およびマトリクス(matrix)、range(レンジ、範囲)、文字列(character string)、データ構造型(data structure type)、セル配列(cell array)です。将来のバージョンで、さらにビルトインデータ型が追加されるかもしれません。現在ビルトイン型として提供されていない、特別なデータ型が必要な場合は、あなたが独自にユーザー定義データ型を記述して、それをOctaveの将来リリースのディストリビューションのために寄贈されることをお勧めします。

以下の関数を使用して、変数のデータ型の判定と変更ができます。

Function File: classname = class (obj)
Function File: class (s, id)
Function File: class (s, id, p, …)

オブジェクトobjのクラスをリターン、または構造sのフィールド、およびnameフィールド(文字列)がidのクラスを作成します。追加の引数は、新しいクラスがどのクラスから継承されたかを示す親クラスの名前のリストです。

See also: typeinfo, isa.

Function File: isa (obj, classname)

objがクラスclassnameならばtrueをリターンします。

classnameは、以下のクラスカテゴリーの1つかもしれません:

"float"

float(浮動小数点)の値は、クラス"double"および"single"を包括します。

"integer"

integer(整数)の値は、クラス(u)int8、(u)int16、(u)int32、(u)int64を包括します。

"numeric"

numericの値は、浮動小数点値と整数値を包括します。

See also: class, typeinfo.

Function File: cast (val, type)

valをデータ型typeに変換します。

See also: int8, uint8, int16, uint16, int32, uint32, int64, uint64, double.

Built-in Function: typecast (x, class)

メモリー内でxのデータをnumericクラスclassのデータとして解釈し、結果を新たな配列yでリターンします。xclassはどちらも、ビルトインnumericクラスの1つでなければなりません。

 
"logical"
"char"
"int8"
"int16"
"int32"
"int64"
"uint8"
"uint16"
"uint32"
"uint64"
"double"
"single"
"double complex"
"single complex"

最後の2つは、classのために予約されています。これらは、complex値の結果が要求されていることを示します。complex配列は、連続するreal値として、メモリー内に格納されます。integer型のサイズは、それらのビット数で与えられます。logicalとcharはどちらも1バイト幅です。しかしこれはC++により保証されていません。システムがIEEE準拠の場合、singleとdoubleは、4バイトおよび8バイト幅です。"logical"は、classに指定できません。入力が行ベクターならリターン値は行ベクターで、それ以外は列ベクターです。xのビット長がclassのビット長の倍数でない場合は、エラーが発生します。

リトルエンディアン機でtypecastを使用する例は

 
x = uint16 ([1, 65535]);
typecast (x, "uint8")
⇒ [   1,   0, 255, 255]

See also: cast, bitunpack, bitpack, swapbytes.

Function File: swapbytes (x)

値のバイト順を入れ替えて、リトルエンディアンからビッグエンディアン、またはその逆の変換をします。

 
swapbytes (uint16 (1:4))
⇒ [   256   512   768  1024]

See also: typecast, cast.

Built-in Function: y = bitpack (x, class)

配列xをnumericクラスclassのrawビット配列として解釈した結果を、新たな配列yでリターンします。classはビルトインnumericクラスのうちの1つでなければなりません。

 
"char"
"int8"
"int16"
"int32"
"int64"
"uint8"
"uint16"
"uint32"
"uint64"
"double"
"single"

xの要素の個数は、classのビット長の倍数である必要があります。もしそうでない場合には、余分なビットは無視されます。ビット順は、x(1)がビット0、x(2)がビット1、のように、昇順になっています。結果は、xが行ベクターなら行ベクター、それ以外は列ベクターになります。

See also: bitunpack, typecast.

Built-in Function: y = bitunpack (x)

xのrawビットパターンに対応する配列yをリターンします。xはビルトインnumericクラスの1つに属していなければなりません:

 
"char"
"int8"
"int16"
"int32"
"int64"
"uint8"
"uint16"
"uint32"
"uint64"
"double"
"single"

結果はxが行ベクターなら行ベクター、それ以外は列ベクターです。

See also: bitpack, typecast.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1.1 Numeric Objects

Octaveのビルトインnumericオブジェクトには、real、complex、integerのスカラーとマトリクスが含まれます。すべてのビルトイン浮動小数点numericデータは、現在のところ倍精度浮動小数点数として格納されます。IEEE浮動小数点フォーマットを使用するシステムでは、およそ 2.2251e-308から1.7977e+308 までの範囲の値が格納でき、相対精度はおよそ 2.2204e-16です。 正確な値はそれぞれ、変数realminrealmaxepsで得ることができます。

マトリクスオブジェクトは任意のサイズをとることができ、動的に変形やサイズ変更ができます。種々の強力なインデクス機能を使用して、特定の行や列、サブマトリクスが簡単に抽出できます。Index Expressionsを参照してください。

詳細は、Numeric Data Typesを参照してください。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1.2 Missing Data

Octaveでは、NA(“Not Available”の略)を使用して、欠損データを明示的に表すことができます。欠損データが表されるのは、データが浮動小数点数として表されるときだけです。この場合、欠損データはNaNの特別なケースとして表されます。

Built-in Function: NA
Built-in Function: NA (n)
Built-in Function: NA (n, m)
Built-in Function: NA (n, m, k, …)
Built-in Function: NA (…, class)

すべての要素が、欠損値を示すために使用される特別な定数と等しいようなスカラー、マトリクス、N次元配列をリターンします。

NAとNAの比較は常にノットイコール(NA != NA)になることに注意してください。NA値を見つける場合には、isna関数を使用してください。

引数を指定しないで呼び出された場合は、値‘NA’のスカラーをリターンします。1つの引数で呼び出された場合は、指定された次元の正方マトリクスをリターンします。2つ以上のスカラー引数で呼び出された場合、最初の2つは行数と列数を指定し、残りは追加のマトリクス次元を指定します。オプション引数classは、リターン型を指定し、"double""single"です。

See also: isna.

Mapping Function: isna (x)

xの要素がNA値(欠損値)のところはtrue、異なるところはfalseであるようなlogical配列をリターンします。たとえば:

 
isna ([13, Inf, NA, NaN])
     ⇒ [ 0, 0, 1, 0 ]

See also: isnan, isinf, isfinite.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1.3 String Objects

Octaveでの文字列は、ダブルクォーテーション、またはシングルクォーテーションで囲まれた文字シーケンスで構成されます。内部的には現在のところ、Octaveは文字列を文字のマトリクスとして格納します。マトリクスオブジェクトに機能するインデクス操作のすべては、文字列にたいしても機能します。

詳細は、Stringsを参照してください。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1.4 Data Structure Objects

Octaveにデータ構造型は、異なる型の関連するオブジェクトを組織化する助けになります。現在の実装では、インデクスが文字列に限定された連想配列を使用しますが、構文はCスタイルの構造体に類似しています。

詳細は、Structuresを参照してください。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1.5 Cell Array Objects

Octaveのセル配列(Cell Array)は、異なるデータ型を任意個もつことができる、汎用配列です。

詳細は、Cell Arraysを参照してください。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2 User-defined Data Types

わたしはいつかOctaveのユーザー定義データ型の管理にたいする管理メカニズムについての完全なドキュメントを含めることで、このセクションを拡張したいと思っています。ここにその機能がドキュメントされるまで、あなたがそれを行なうためには、Octaveの‘src’ディレクトリーにある‘ov.h’、‘ops.h’、および関連するファイルのコードを読む必要があるでしょう。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3 Object Sizes

以降の関数により、変数や式のサイズを判定できます。これらの関数は、すべてのオブジェクトにたいして定義されています。これらは操作に意味がない場合は、-1をリターンします。たとえば、Octaveのデータ構造型は行や列を持たないので、rowscolumnsの関数は、構造型の引数にたいしては、-1をリターンします。

Built-in Function: ndims (a)

aの次元数をリターンします。任意の配列にたいし、結果は2以上になります。後続のシングルトン次元(singleton dimension: 1と等しい次元)はカウントされません。

 
ndims (ones (4, 1, 2, 1))
    ⇒ 3

See also: size.

Built-in Function: columns (a)

aの列数をリターンします。

See also: rows, size, length, numel, isscalar, isvector, ismatrix.

Built-in Function: rows (a)

aの行数をリターンします。

See also: columns, size, length, numel, isscalar, isvector, ismatrix.

Built-in Function: numel (a)
Built-in Function: numel (a, idx1, idx2, …)

オブジェクトa内の要素数をリターンします。オプションで、もしidx1idx2、…が与えられた場合は、インデクス操作の結果

 
a(idx1, idx2, …)

の要素数をリターンします。インデクスは数値である必要はないことに注意してください。たとえば、

 
a = 1;
b = ones (2, 3);
numel (a, b)

こてはbでインデクスをつける方法で、6をリターンします。

この手法は、オブジェクトがcsリスト(カンマ区切りリスト)のインデクス操作のlvalue(左辺値)として現れたときにも使用されます(例: object{…}またはobject(…).field)。

See also: size.

Built-in Function: length (a)

オブジェクトaの長さをリターンします。

lengthは、空のオブジェクトにたいしては0、スカラーにたいしては1、ベクターにたいしては要素数です。マトリクスオブジェクトについては、行数または列数の大きい方がlengthになります(この奇妙な定義は、MATLABとの互換のために使用されます)。

See also: numel, size.

Built-in Function: size (a)
Built-in Function: size (a, dim)

aの行数と列数をリターンします。

入力引数が1つで、出力引数が1つの場合、結果は行ベクターでリターンされます。出力引数が複数の場合、行数が1つ目、列数が2つ目の出力引数、などとなります。たとえば:

 
size ([1, 2; 3, 4; 5, 6])
   ⇒ [ 3, 2 ]

[nr, nc] = size ([1, 2; 3, 4; 5, 6])
    ⇒ nr = 3
    ⇒ nc = 2

2つ目の引数が与えられた場合、sizeは対応する次元のサイズをリターンします。たとえば、

 
size ([1, 2; 3, 4; 5, 6], 2)
    ⇒ 2

これは与えられたマトリクスの列数をリターンします。

See also: numel, ndims, length, rows, columns.

Built-in Function: isempty (a)

aが空のマトリクス(マトリクスの次元のうち1つが0)の場合はtrue、それ以外はfalseをリターンします。

See also: isnull, isa.

Built-in Function: isnull (x)

xがマトリクス、文字列、シングルクォートされた文字列で、それらが特別な値nullの場合は、trueをリターンします。右辺にこのような値があるインデクス割り当てでは、配列の要素が削除されます。以下のようなケースと区別するため、ユーザー定義クラスのインデクス割り当てのオーバーロードでは、isemptyのかわりにこの関数を使用するべきです:

A(I) = []

これはIが空でない場合は、要素を削除します。

X = []; A(I) = X

これは、Iが空でない場合は、エラーになります。

See also: isempty, isindex.

Built-in Function: sizeof (val)

valのサイズをバイトでリターンします。

See also: whos.

Built-in Function: size_equal (a, b, …)

すべての引数の次元が一致する場合は、trueをリターンします。後続のシングルトン次元は無視されます。引数が1つ、または指定されない場合、size_equalはtrueをリターンします。

See also: size, numel, ndims.

Built-in Function: squeeze (x)

xからシングルトン次元を削除して、その結果をリターンします。MATLABとの互換のため、すべてのオブジェクトは少なくとも2つの次元をもち、行ベクターは変更されません。

See also: reshape.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4. Numeric Data Types

numeric定数はスカラー、ベクター、マトリクスであるかもしれず、さらにそれらはcomplex値を含むかもしれません。

もっともシンプルなnumeric定数の形式はスカラーです。スカラーは単独の数であり、整数、少数、科学表記(指数表記)の数値、複素数を含むことができます。Octave内ではデフォルトではnumeric定数は倍精度浮動小数点数で表されることに注意してください(complex定数は倍精度浮動小数点数のペアーとして格納されます)。しかし、Integer Data Typesで説明するように、real整数(実数型整数)で表すこともできます。以下にreal値のnumeric定数の例をいくつか示します。これらはすべて同じ値をもちます:

 
105
1.05e+2
1050e-1

complex定数を指定する場合は、以下の形式で式を記述できます

 
3 + 4i
3.0 + 4.0i
0.3e1 + 40e-1i

これらはすべて等価です。この例の文字‘i’は純虚数定数(pure imaginary constant)を意味しており、 sqrt (-1)と定義されます。

Octaveがcomplex定数の虚部(imaginary part)を認識するためには、数字と‘i’の間にスペースがあってはなりません。スペースが存在する場合、Octaveは以下のようなエラーメッセージをプリントします:

 
octave:13> 3 + 4 i

parse error:

  syntax error

>>> 3 + 4 i
          ^

上記の例で‘i’が出現する箇所には‘j’、‘I’、‘J’を使うこともできます。これら4つの形式は、すべて等価です。

Built-in Function: double (x)

xを倍精度型に変換します。

See also: single.

Built-in Function: complex (x)
Built-in Function: complex (re, im)

realの引数から、complexの結果をリターンします。realの引数がxの1つの場合、結果はcomplexのx + 0iになります。realの引数が2つの場合、結果はcomplexのre + imになります。a + i*bのような式よりも、complexのほうが便利な場合もあります。たとえば:

 
complex ([1, 2], [3, 4])
  ⇒ [ 1 + 3i   2 + 4i ]

See also: real, imag, iscomplex, abs, arg.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1 Matrices

Octaveで値のマトリクスを定義するのは、簡単です。マトリクスのサイズは自動的に決定されるので、次元を明示する必要はありません。以下の式

 
a = [1, 2; 3, 4]

の結果は、以下のマトリクスになります

 
        /      \
        | 1  2 |
  a  =  |      |
        | 3  4 |
        \      /

さまざまなピースをまとめたときに、すべての次元が意味をなすなら、任意の式をマトリクスの要素にできます。たとえば、上記のマトリクスが与えられた場合、以下の式

 
[ a, a ]

は、以下のマトリクスを生成します

 
ans =

  1  2  1  2
  3  4  3  4

しかし、以下の式

 
[ a, 1 ]

は、エラーを生成します

 
error: number of rows must match (1 != 2) near line 13, column 6

(このエラーは、この式が13行目の行頭から入力された場合です)。

マトリクス式を区切る角カッコの中では、スペース文字と改行文字を要素と行区切りに変換すべきか、あるいは単に無視すべきかを判断するために、Octaveは周囲のコンテキストを調べます。そのため、以下のような式

 
a = [ 1 2
      3 4 ]

は機能するでしょう。しかし混乱の種はまだ残っています。たとえば、以下の式

 
[ 1 - 1 ]

では‘-’は2項演算子とみなされ、その結果はスカラー0になります。しかし以下の式

 
[ 1 -1 ]

では‘-’は単項演算子とみなされ、結果はベクター[ 1, -1 ]になります。同様に、以下の式

 
[ sin (pi) ]

は以下のよyにパースされて

 
[ sin, (pi) ]

これはsin関数が引数なしで呼び出されたとみなされて、エラーになります。エラーを回避するためには、sinと開きカッコの間のスペースを取り除くか、式をカッコで括らなければなりません:

 
[ (sin (pi)) ]

転置演算子(transpose operator)と文字列の区切りに使用される、空白文字ど囲まれたシングルクォート文字(‘'’も混乱を招きます。a = 1が与えられた場合、以下の式

 
[ 1 a' ]

では、シングルクォート文字は転置演算子とみなされて、結果はベクター[ 1, 1 ]になります。しかし以下の式

 
[ 1 a ' ]

はエラーメッセージを生成します

 
parse error:

  syntax error

>>> [ 1 a ' ]
              ^

なぜなら、これをエラーにしないと、以下のような有効な式をパースするときトラブルになるからです

 
[ a 'foo' ]

明確にするためには、マトリクスの要素と行の区切りには常に、カンマとセミコロンを使用するのがおそらく最善でしょう。

マトリクスの要素の最大数は、Octaveのコンパイル時に決定されていて固定です。可能な数は、関数sizemaxで問い合わせることができます。マシン上で利用できるメモリーなど、他の要因により、マトリクスの最大要素数の制限は、いくぶん小さくなるかもしれないことに注意してください。

Built-in Function: sizemax ()

配列のサイズにたいして許される最大の値をリターンします。Octaveが64-bit indexingでコンパイルされている場合はint64クラスの最大値、それ以外はint32クラスの最大値になります。配列の最大サイズは、intmaxでリポートされる関連するクラスに許される最大値より、少しだけ小さくなります。

See also: intmax.

マトリクス、または値がマトリクスである変数の名前をタイプすると、Octaveは行と列を整列してプリントします。そのマトリクスの行がスクリーンに収まらないほど大きい場合、Octaveはマトリクスを分割して、どの列が表示されているかを示すヘッダーを各セクションの前に表示します。出力フォーマットを制御するために、以下の変数を使用できます。

Built-in Function: val = output_max_field_width ()
Built-in Function: old_val = output_max_field_width (new_val)
Built-in Function: output_max_field_width (new_val, "local")

numeric出力フィールドの最大幅を指定する内部変数にたいして、問い合わせまたはセットを行います。

関数の中から"local"オプションと共に呼び出された場合、変数の変更はその関数または関数のサブルーチンにたいしてローカルになります。関数をexitするとき、変数の元の値がリストアされます。

See also: format, fixed_point_format, output_precision.

Built-in Function: val = output_precision ()
Built-in Function: old_val = output_precision (new_val)
Built-in Function: output_precision (new_val, "local")

numeric出力にたいして表示する最小の有効数字を指定する内部変数にたいして、問い合わせまたはセットを行います。

関数の中から"local"オプションと共に呼び出された場合、変数の変更はその関数または関数のサブルーチンにたいしてローカルになります。関数をexitするとき、変数の元の値がリストアされます。

See also: format, fixed_point_format, output_max_field_width.

output_precisionoutput_max_field_widthに異なる値を使用することにより、幅広い出力スタイルを実現できます。format関数をセットして、妥当な組み合わせをセットできます。Basic Input and Outputを参照してください。

Built-in Function: val = split_long_rows ()
Built-in Function: old_val = split_long_rows (new_val)
Built-in Function: split_long_rows (new_val, "local")

端末ウィンドウに表示するときにマトリクスの行を分割するかどうかを制御する内部変数にたいして、問い合わせまたはセットを行います。行を分割する場合、Octaveはマトリクスを小さい断片のシリーズとして表示します。断片はそれぞれ、端末の制限幅に適合するよう分割され、各行セットにはラベルが付されるので、現在どの列が表示されているか簡単に識別できます。たとえば:

 
octave:13> rand (2,10)
ans =

 Columns 1 through 6:

  0.75883  0.93290  0.40064  0.43818  0.94958  0.16467
  0.75697  0.51942  0.40031  0.61784  0.92309  0.40201

 Columns 7 through 10:

  0.90174  0.11854  0.72313  0.73326
  0.44672  0.94303  0.56564  0.82150

関数の中から"local"オプションと共に呼び出された場合、変数の変更はその関数または関数のサブルーチンにたいしてローカルになります。関数をexitするとき、変数の元の値がリストアされます。

See also: format.

値が非常に大きくなったとき、または小さくなったとき、Octaveは自動的に科学的表記に切り替えます。これはマトリクス内のすべての値にたいして、数桁の有効数字を確認できることを保証します。マトリクス内のすべての値を固定小数点フォーマットで確認したい場合は、ビルトイン変数fixed_point_formatを非0値にセットすることができます。しかしこれを行なうことにより、容易に誤解釈され得る出力を生成するため、推奨されません。

Built-in Function: val = fixed_point_format ()
Built-in Function: old_val = fixed_point_format (new_val)
Built-in Function: fixed_point_format (new_val, "local")

Octaveがマトリクスの値をプリントするためにスケール化されたフォーマットを使用するかどうかを制御する内部変数にたいして、問い合わせまたはセットを行います。

スケール化されたフォーマットは、出力の最初の行にスケール因子をプリントします。スケール因子はマトリクスの最大要素を、整数部1桁で記述できるように選択されます。たとえば:

 
logspace (1, 7, 5)'
ans =

  1.0e+07  *

  0.00000
  0.00003
  0.00100
  0.03162
  1.00000

最初の値は実際は1なのに、0のように見えることに注目してください。混乱を招く可能性があるため、fixed_point_formatの有効化には注意が必要です。

関数の中から"local"オプションと共に呼び出された場合、変数の変更はその関数または関数のサブルーチンにたいしてローカルになります。関数をexitするとき、変数の元の値がリストアされます。

See also: format, output_max_field_width, output_precision.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.1.1 Empty Matrices

マトリクスの1つ、または両方の次元が0の場合があり、このような空マトリクスへの操作は、Carl de Boor in An Empty Exercise, SIGNUM, Volume 25, pages 2-6, 1990 and C. N. Nett and W. M. Haddad, in A System-Theoretic Appropriate Realization of the Empty Matrix Concept, IEEE Transactions on Automatic Control, Volume 38, Number 5, May 1993で説明されています。 簡単にいうと、スカラーsmn列のマトリクスM(mxn)mn列の空マトリクス(1つまたは両方の次元が0)[](mxn)が与えられたとき、以下が成り立ちます:

 
s * [](mxn) = [](mxn) * s = [](mxn)

    [](mxn) + [](mxn) = [](mxn)

    [](0xm) *  M(mxn) = [](0xn)

     M(mxn) * [](nx0) = [](mx0)

    [](mx0) * [](0xn) =  0(mxn)

デフォルトでは、空マトリクスの次元は、空マトリクスのシンボル‘[]’と共にプリントされます。ビルトイン変数print_empty_dimensionsが、この振る舞いを制御します。

Built-in Function: val = print_empty_dimensions ()
Built-in Function: old_val = print_empty_dimensions (new_val)
Built-in Function: print_empty_dimensions (new_val, "local")

空マトリクスの次元を空マトリクスのシンボル‘[]’と共にプリントするかどうかを制御する内部変数にたいして、問い合わせまたはセットを行います。たとえば、以下の式

 
zeros (3, 0)

は、以下のようにプリントするでしょう

 
ans = [](3x0)

関数の中から"local"オプションと共に呼び出された場合、変数の変更はその関数または関数のサブルーチンにたいしてローカルになります。関数をexitするとき、変数の元の値がリストアされます。

See also: format.

空マトリクスは、マトリクスから行や列を簡単に削除する方法として、割り当てステートメント内でも使用されます。Assignment Expressionsを参照してください。

Octaveがマトリクス式をパースする場合な要素がすべて定数かどうか、要素のリストを調べます。そして、すべて定数ならば、そのリストを1つのマトリクス定数に置き換えます。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2 Ranges

レンジ(range: 範囲)は、等差の要素からなる行ベクターを記述する便利な方法です。レンジ式は、そのレンジ内の最初の値、オプションとして要素間の増分値、そしてそのレンジの要素の上限となる最大値により定義されます。これらのベース、増分、リミットはコロン(‘:’文字)で区切られ、任意の算術式や関数呼び出しを含むことができます。増分が省略された場合、増分は1とみなされます。たとえば、以下のレンジ

 
1 : 5

は、値‘[ 1, 2, 3, 4, 5 ]’を定義します。また、以下のレンジ

 
1 : 3 : 5

は、値‘[ 1, 4 ]’を定義します。

レンジ定数で行ベクターを指定しても、Octaveは変換する必要がなければ、レンジ定数をベクターに変換しません。これにより、‘1 : 10000’のような定数を記述しても、ストレージを消費(通常の32ビットワークステーション上では8000バイト)せずにすみます。

レンジをベクターに変換する必要が生じる例としては、それらがベクター(例: 角カッコの内側)と共に記述されるときです。たとえば、

 
x = 0 : 0.1 : 1;

これは、xrange型として定義し、式のために24バイトのメモリーを占めます

 
y = [ 0 : 0.1 : 1];

これは、ymatrix型として定義し、88バイトのメモリーを占めます。

レンジの上限(増分が負の場合は下限)は常に値セットに含まれるとは限らないこと、そして浮動小数点で定義されたレンジは、レンジ内の値の計算にOctaveが浮動小数演算を使用するので、驚くような結果を生成するかもしれないことに注意してください。レンジの終端を含めることが重要で、なおかつ要素数が既知の場合は、linspace関数(Special Utility Matrices参照)をかわりに使用してください。

レンジにたいするスカラーの加算と減算(またはスカラーからレンジの減算)、および乗算の場合、Octaveじゃレンジの展開を試みずに、展開しても安全だと判断できるまで、結果をレンジのまま保留します。たとえば、

 
a = 2*(1:1e7) - 1;

これは‘1:2:2e7-1’と同じ結果を生成しますが、1000万個の要素をもつベクターが生成されるわけではありません。

コロン表記で‘1:0:1’のように増分に0を使用するのは、レンジ要素の個数を決定するとき0除算が発生するために、許されていません。しかし、増分0(例: すべての要素が同じ)のレンジは有用(よく特にインデクス操作において)なので、Octaveではビルトイン関数onesを使用してそれらを構築できます。レンジは行にベクターでなければならないので、‘ones (1, 10)’はレンジを構成しますが、‘ones (10, 1)’はレンジを構成しません。

Octaveがレンジ式をパースするとき、その式の要素がすべて定数かどうか調べます。そして、すべて定数の場合は、そのレンジ式を1つのレンジ定数で置き換えます。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.3 Single Precision Data Types

Octaveには単精度データ型(single precision data type)にたいするサポートがおり、Octave内のほとんどの関数は、単精度値を受け入れ、単精度の答えをリターンします。単精度変数は、single関数で作成します。

Built-in Function: single (x)

xを単精度型に変換します。

See also: double.

たとえば:

 
sngl = single (rand (2, 2))
     ⇒ sngl = 
        0.37569   0.92982
        0.11962   0.50876
class (sngl)
    ⇒ single

多くの関数は、単精度値を直接リターンすることもできます。たとえば

 
ones (2, 2, "single")
zeros (2, 2, "single")
eye (2, 2,  "single")
rand (2, 2, "single")
NaN (2, 2, "single")
NA (2, 2, "single")
Inf (2, 2, "single")

これはすべて単精度マトリクスをリターンします。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.4 Integer Data Types

Octaveは倍精度を使用する代替えとして、整数マトリクスをサポートします。8、16、32、64ビットで表される、符号つき、および符号なし整数の両方が使用できます。整数は数値演算により型が変化するときがあるので、多くの演算では浮動小数点データが要求されることは注記しておくべきでしょう。この理由により、整数がもっとも使用されるのは計算ではなく、データの格納においてです。

一般的に、整数マトリクスのほとんどは、既存のマトリクスを整数にキャストすることにより作成されます。以下は、マトリクスを32ビット整数にキャストする方法の例です。

 
float = rand (2, 2)
     ⇒ float = 0.37569   0.92982
                0.11962   0.50876
integer = int32 (float)
     ⇒ integer = 0  1
                  0  1

確認できるように、浮動小数点値は変換時にもっとも近い整数に丸められます。

Built-in Function: isinteger (x)

xが整数オブジェクト(int8、uint8、int16、など)の場合はtrueをリターンします。Octave内部では数値定数は倍精度浮動小数点値なので、isinteger (14)はfalseになることに注意してください。

See also: isfloat, ischar, islogical, isnumeric, isa.

Built-in Function: int8 (x)

xを8ビット整数型に変換します。

See also: uint8, int16, uint16, int32, uint32, int64, uint64.

Built-in Function: uint8 (x)

xを符号なし8ビット整数型に変換します。

See also: int8, int16, uint16, int32, uint32, int64, uint64.

Built-in Function: int16 (x)

xを16ビット整数型に変換します。

See also: int8, uint8, uint16, int32, uint32, int64, uint64.

Built-in Function: uint16 (x)

xを符号なし16ビット整数型に変換します。

See also: int8, uint8, int16, int32, uint32, int64, uint64.

Built-in Function: int32 (x)

xを32ビット整数型に変換します。

See also: int8, uint8, int16, uint16, uint32, int64, uint64.

Built-in Function: uint32 (x)

xを符号なし32ビット整数型に変換します。

See also: int8, uint8, int16, uint16, int32, int64, uint64.

Built-in Function: int64 (x)

xを64ビット整数型に変換します。

See also: int8, uint8, int16, uint16, int32, uint32, uint64.

Built-in Function: uint64 (x)

xを符号なし64ビット整数型に変換します。

See also: int8, uint8, int16, uint16, int32, uint32, int64.

Built-in Function: intmax (type)

整数型として表すことができる、もっとも大きな整数をリターンします。変数type

int8

signed 8-bit integer.

int16

符号つき16ビット整数

int32

符号つき32ビット整数

int64

符号つき64ビット整数

uint8

符号なし8ビット整数

uint16

符号なし16ビット整数

uint32

符号なし32ビット整数

uint64

符号なし64ビット整数

typeのデフォルト値はint32です。

See also: intmin, flintmax, bitmax.

Built-in Function: intmin (type)

整数型として表すことができる、もっとも小さな整数をリターンします。変数type

int8

signed 8-bit integer.

int16

符号つき16ビット整数

int32

符号つき32ビット整数

int64

符号つき64ビット整数

uint8

符号なし8ビット整数

uint16

符号なし16ビット整数

uint32

符号なし32ビット整数

uint64

符号なし64ビット整数

typeのデフォルト値はint32です。

See also: intmax, flintmax, bitmax.

Built-in Function: flintmax ()
Built-in Function: flintmax ("double")
Built-in Function: flintmax ("single")

浮動小数点値として一貫(consecutively)して表すことができる、最大の整数をリターンします。デフォルトクラスは"double"ですが、"single"も有効なオプションです。IEEE-754互換システムでは、flintmax"double"にたいして2^53"single"にたいして2^24です。

See also: bitmax, intmax, realmax, realmin.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.4.1 Integer Arithmetic

整数に適用できない数値演算はたくさんありますが、Octaveは整数にたいして加算や乗算のような基本的な操作をサポートします。同じ型の整数にたいして+-.*./の演算子が機能します。つまり2つの32ビット整数の加算はできますが、32ビット整数と16ビット整数の加算はできません。

整数演算を行う場合、アンダーフローとオーバーフローの可能性を考慮すべきです。これは選択した整数型を使用して、演算結果を表現できないときに発生します。たとえば、符号なし整数を使用している場合は、10 - 20の結果は表現できません。そのような場合、Octaveは整数演算の結果を、真の結果に近い整数にします。したがって10 - 20の結果は、符号なし整数を使用している場合は0になります。

整数の除算では、Octaveは結果をもっとも近い整数に丸めます。多くの言語では結果はもっとも近い整数に切り下げる場合が多いので、Octaveとは異なります。Octaveでは、int32 (5) ./ int32 (8)の結果は1になります。

Function File: idivide (x, y, op)

別の丸め規則により整数の除算を行います。

標準では、a ./ bのような整数除算にたいして、結果はもっとも近い整数に丸められます。これは常に望んだ振る舞いではないため、idiqvideは要素ごとの除算による少数部にたいして、opフラグにより異なる扱いをします。opは以下の文字列です:

"fix"

a ./ bを計算して、少数部を0に丸めます。

"round"

a ./ bを計算して、少数部をもっとも近い整数に丸めます。

"floor"

a ./ bを計算して、少数部を負の無限大に丸めます。

"ceil"

a ./ bを計算して、少数部を正の無限大に丸めます。

以下の例は、opにデフォルト"fix"以外が与えられた場合の、これらの丸め規則の実例です

 
idivide (int8 ([-3, 3]), int8 (4), "fix")
  ⇒ int8 ([0, 0])
idivide (int8 ([-3, 3]), int8 (4), "round")
  ⇒ int8 ([-1, 1])
idivide (int8 ([-3, 3]), int8 (4), "floor")
  ⇒ int8 ([-1, 0])
idivide (int8 ([-3, 3]), int8 (4), "ceil")
  ⇒ int8 ([0, 1])

See also: ldivide, rdivide.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.5 Bit Manipulations

Octaveは、数値をビット単位で操作するいくつかの関数を提供します。特定のビットの値のセットと取得を行う基本的な関数は、bitsetbitgetです。

Function File: C = bitset (A, n)
Function File: C = bitset (A, n, val)

A内の符号なし整数のnビットにたいして、セットまたはリセットを行います。val = 0の場合はリセット、val = 1の場合はセットを行います。最小の有効なビットは、n = 1です。すべての変数は同サイズまたは、スカラーでなければなりません。

 
dec2bin (bitset (10, 1))
  ⇒ 1011

See also: bitand, bitor, bitxor, bitget, bitcmp, bitshift, bitmax.

Function File: c = bitget (A, n)

符号なし整数A内の、ビットnの状態をリターンします。有効な最小のビットはn = 1です。

 
bitget (100, 8:-1:1)
⇒ 0  1  1  0  0  1  0  0

See also: bitand, bitor, bitxor, bitset, bitcmp, bitshift, bitmax.

Octaveのビット単位操作の引数はすべて、bitcmpを除き、スカラーまたは配列を指定できます(bitcmpの引数kはスカラーでなければなりません)。1つ以上の引数が配列の場合は、すべての引数が同じ形状でなければならず、ビット単位操作は引数の個別の要素ごとに適用されます。少なくとも1つの引数がスカラーで、配列もある場合は、スカラー引数が複製されます。したがって

 
bitget (100, 8:-1:1)

は、以下と同じです

 
bitget (100 * ones (1, 8), 8:-1:1)

Octaveのビット操作関数に渡されるすべての値は、整数として扱われることを注記しておくべきでしょう。師、たとえ上記の例のbitsetに浮動小数点値10を渡しても、10にたいする浮動小数点フォーマットのネイティブ表現ではなく、ビット[1, 0, 1, 0]として扱われます。

ビット操作にとって、数値として表すことのできる最大値は、特にマスク処理を行う場合に重要なので、Octaveは関数bitmaxを提供します。

Built-in Function: bitmax ()
Built-in Function: bitmax ("double")
Built-in Function: bitmax ("single")

浮動小数点値として表すことのできる最大の整数値をリターンします。デフォルトクラスは"double"ですが、"single"も有効なオプションです。IEEE-754互換システムでのbitmaxは、"double"にたいしては2^53 - 1"single"にたいしては2^24 -1です。

See also: flintmax, intmax, realmax, realmin.

これは前に説明した関数intmaxの倍精度バージョンです。

Octaveにはビット単位の演算子、’積(and)’、’和(or)’、’排他的論理和(exclusive or)’もあります。

Built-in Function: bitand (x, y)

非負の整数のビットごとのANDをリターンします。xyは、レンジ[0,bitmax]以内でなければなりません。

See also: bitor, bitxor, bitset, bitget, bitcmp, bitshift, bitmax.

Built-in Function: bitor (x, y)

非負の整数のビットごとのORをリターンします。xyは、レンジ[0,bitmax]以内でなければなりません。

See also: bitor, bitxor, bitset, bitget, bitcmp, bitshift, bitmax.

Built-in Function: bitxor (x, y)

非負の整数のビットごとのXORをリターンします。xyは、レンジ[0,bitmax]以内でなければなりません。

See also: bitand, bitor, bitset, bitget, bitcmp, bitshift, bitmax.

ビット単位の’否定(not)’は、値の各ビットにたいして論理否定を行う、単項演算子です。これは否定しようとする値のマスクを定義しなければならないときに有用です。Octaveのビットごとの’否定(not)’演算子は、bitcmpです。

Function File: bitcmp (A, k)

A内の整数のkビット補数をリターンします。kは省略された場合、k = log2 (bitmax) + 1が指定されたとみなします。

 
bitcmp (7,4)
  ⇒ 8
dec2bin (11)
  ⇒ 1011
dec2bin (bitcmp (11, 6))
  ⇒ 110100

See also: bitand, bitor, bitxor, bitset, bitget, bitcmp, bitshift, bitmax.

Octaveには、値にたいしてビット単位での左シフトと右シフトの機能もあります。

Built-in Function: bitshift (a, k)
Built-in Function: bitshift (a, k, n)

a内の符号なし整数をkビットシフトして、結果のn桁(ビット)をリターンします。kの値が正ならば左シフト、負ならば右シフトです。nが省略された場合のデフォルトは、log2(bitmax)+1です。nはレンジ[1,log2(bitmax)+1](通常は[1,33])以内でなければなりません。

 
bitshift (eye (3), 1)
⇒
2 0 0
0 2 0
0 0 2
bitshift (10, [-2, -1, 0, 1, 2])
⇒ 2   5  10  20  40

See also: bitand, bitor, bitxor, bitset, bitget, bitcmp, bitmax.

値の両方の終端からシフトアウトされたビットは失われます。Octaveは数学的シフト(右シフトにおいて値の符号ビットが保持される)も使用します。たとえば:

 
bitshift (-10, -1)
⇒ -5
bitshift (int8 (-1), -1)
⇒ -1

bitshift (int8 (-1), -1)-1になることに注意してください。これはint8データ型における-1のビット表現が[1, 1, 1, 1, 1, 1, 1, 1]だからです。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.6 Logical Values

Octaveには論理値(例: 値がtruefalseであるような変数)にたいするビルトインサポートがあります。2つの変数を比較する場合、結果はその比較の結果が真か否かに依存する値をもつ、論理値になります。

基本的な論理演算子&|!はそれぞれ“論理AND”、“論理OR”、“論理NOT”に対応します。これらの演算子は通常の論理ルールにしたがいます。

標準的な数値計算の一部として論理値を使うこともできます。この場合、true1false0に変換され、それらは倍精度浮動小数点数で表されます。つまりtrue*22 - false/622になります。

論理値はマトリクスとセル配列のインデクスにも使用されます。論理配列でインデクス操作を行う場合、結果は論理配列のtrue部に対応する値を含むベクターになります。以下の例で示します。

 
data = [ 1, 2; 3, 4 ];
idx = (data <= 2);
data(idx)
     ⇒ ans = [ 1; 2 ]

idx配列を作成せずに、上記コードのdata(idx)data( data <= 2 )に置き換えることも可能です。

論理値は、数値オブジェクトから論理値へのキャストや、trueおよびfalseの関数で構築することもできます。

Built-in Function: logical (x)

数値オブジェクトxを論理型に変換します。

非0値はtrue(1)に、0値はfalse(0)に変換されます。非数値NaNは変換できず、エラーが発生します。

互換性ノート: Octaveでは複素数値を入力できますが、MATLABはできません。

See also: double, single, char.

Built-in Function: true (x)
Built-in Function: true (n, m)
Built-in Function: true (n, m, k, …)

要素がすべて論理的1であるような行列またはN次元配列をリターンします。引数が1つのスカラー整数の場合は、指定されたサイズの正方マトリクスリターンします。引数が2つ以上のスカラー整数、または整数値ベクターの場合は、与えられた次元の配列をリターンします。

See also: false.

Built-in Function: false (x)
Built-in Function: false (n, m)
Built-in Function: false (n, m, k, …)

要素がすべて論理的0であるような行列またはN次元配列をリターンします。引数が1つのスカラー整数の場合は、指定されたサイズの正方マトリクスリターンします。引数が2つ以上のスカラー整数、または整数値ベクターの場合は、与えられた次元の配列をリターンします。

See also: true.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.7 Promotion and Demotion of Data Types

混成されたデータ型にたいして機能する演算子と関数が多数あります。たとえば、

 
uint8 (1) + 1
    ⇒ 2

上記の例の演算子は、8ビット整数と倍精度値に作用して、8ビット整数値をリターンしています。型は期待されるように倍精度値に昇格されるのではなく、8ビット整数に降格されたことに注意してください。この理由は、Octaveで上記のような式内の値が昇格されるには、下記のようにすべての数値定数を適切な型に明示的にキャストする必要があるからです

 
uint8 (1) + uint8 (1)
    ⇒ 2

これはユーザーにとって一律に受け入れることを困難にし、混入されるバグの発見を難しくするかもしれません。同じことは、以下のような単精度値にたいする混成演算にも適用されます

 
single (1) + 1
    ⇒ 2

これは単精度値をリターンします。有効な混成演算と、それらがリターンするデータ型は以下のとおりです

混成演算結果
double OP singlesingle
double OP integerinteger
double OP chardouble
double OP logicaldouble
single OP integerinteger
single OP charsingle
single OP logicalsingle

以下のような混成引数による関数呼び出しにも、同じロジックが適用されます

 
min (single (1), 0)
   ⇒ 0

これのリターン値は単精度です。

混成型によるインデクス割り当てでは、型は変更されません。たとえば、

 
x = ones (2, 2);
x(1, 1) = single (2)
   ⇒ x = 2   1
          1   1

ここではxは倍精度型のままです。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.8 Predicates for Numeric Objects

変数のデータ型はプログラム実行の間に変更されるかもしれないので、実行時に型チェックを行う必要が生じます。型チェックを行うことにより、入力のデータ型により関数の振る舞いを変化させることもできます。以下は入力が実数の場合は絶対値、複素数の場合は長さをリターンする、absの単純な実装例です

 
function a = abs (x)
  if (isreal (x))
    a = sign (x) .* x;
  elseif (iscomplex (x))
    a = sqrt (real(x).^2 + imag(x).^2);
  endif
endfunction

以下の関数は変数の型を判断するために利用できます。

Built-in Function: isnumeric (x)

xが数値オブジェクト(例: 整数、実数、複素数の配列など)の場合は、trueをリターンします。論理値と文字配列は、数値とは判断されません。

See also: isinteger, isfloat, isreal, iscomplex, islogical, ischar, iscell, isstruct, isa.

Built-in Function: isfloat (x)

xが浮動小数点数値オブジェクトの場合は、trueをリターンします。倍精度と単精度クラスのオブジェクトは浮動小数点オブジェクトです。

See also: isinteger, ischar, islogical, isnumeric, isa.

Built-in Function: isreal (x)

xが複素数のマトリクスおよびスカラーでない場合は、trueをリターンします。MATLABとの互換性のため、論理値と文字マトリクスを含みます。

See also: iscomplex, isnumeric, isa.

Built-in Function: iscomplex (x)

xが複素数の値をもつ数値オブジェクトの場合は、trueをリターンします。

See also: isreal, isnumeric, islogical, ischar, isfloat, isa.

Built-in Function: ismatrix (a)

aがマトリクス、論理値、文字マトリクスの場合は、trueをリターンします。スカラー(1x1マトリクス)とベクター(1xNマトリクスまたはNx1マトリクスは、一般的なN次元マトリクスのサブセットなので、これらのオブジェクトにたいしてもismatrixは同じようにtrueをリターンします。

See also: isscalar, isvector, iscell, isstruct, issparse, isa.

Function File: isvector (x)

xがベクターの場合は、trueをリターンします。ベクターはどちらか一方の次元が1に等しい2次元配列です。したがって1x1配列とスカラーもベクターです。

See also: isscalar, ismatrix, size, rows, columns, length.

Function File: isrow (x)

xが行ベクターの場合は、trueをリターンします。

See also: iscolumn, isscalar, isvector, ismatrix.

Function File: iscolumn (x)

xが列ベクターの場合は、trueをリターンします。

See also: isrow, isscalar, isvector, ismatrix.

Function File: isscalar (x)

xがスカラーの場合は、trueをリターンします。

See also: isvector, ismatrix.

Function File: issquare (x)

xが正方マトリクスの場合は、trueをリターンします。

See also: isscalar, isvector, ismatrix, size.

Function File: issymmetric (x)
Function File: issymmetric (x, tol)

xtolで指定された公差内で対称なマトリクスの場合は、trueをリターンします。デフォルトの公差は0です(高速なコードを使用します)。マトリクスtolは、norm (x - x.', Inf) / norm (x, Inf) < tolの場合は、対称と判断されます。

See also: ishermitian, isdefinite.

Function File: ishermitian (x)
Function File: ishermitian (x, tol)

xtolで指定された公差内でエルミートの場合は、trueをリターンします。デフォルトの公差は0です(高速なコードを使用します)。マトリクスxは、norm (x - x', Inf) / norm (x, Inf) < tolであれば対称と判断されます。

See also: issymmetric, isdefinite.

Function File: isdefinite (x)
Function File: isdefinite (x, tol)

xtolで指定された公差内で対称な正定値であれば1、xが対称な半正定値であれば0、それ以外は-1をリターンします。tolが省略された場合は、公差100 * eps * norm (x, "fro")を使用します。

See also: issymmetric, ishermitian.

Built-in Function: islogical (x)
Built-in Function: isbool (x)

xが論理オブジェクトの場合は、trueをリターンします。

See also: isfloat, isinteger, ischar, isnumeric, isa.

Function File: isprime (x)

xの要素にたいして、素数の要素にたいしてはtrue、それ以外はfalseであるような論理配列をリターンします。

x内の最大値が非常に大きい場合は、特別な目的のための因数分解コードを使用するべきです。

 
isprime (1:6)
    ⇒ [0, 1, 1, 0, 1, 0]

See also: primes, factor, gcd, lcm.

変数のプロパティを調べるのではなく、どの変数が定義されているかや、ワークスペース自体についての情報を収集したい場合は、Status of Variablesを参照してください。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5. Strings

文字列定数(string constant)は、ダブルクォーテーションマークまたはシングルクォーテーションマークで囲まれた、文字シーケンスにより構成されます。たとえば、以下の式

 
"parrot"
'parrot'

はどちらも内容が‘parrot’の文字列を表します。Octaveでは文字列は任意の長さをとることができます。

シングルクォートマークは転置演算子(Arithmetic Operators参照)にも使用されますが、ダブルクォートマークはOctaveでは他の目的に使用されることはないので、文字列を表すときはダブルクォートマークを使うのが最善です。

文字列の連結はマトリクス定義の記法を使用できます。たとえば、以下の式

 
[ "foo" , "bar" , "baz" ]

は、内容が‘foobarbaz’の文字列を生成します。マトリクスの作成についての詳細は、Numeric Data Typesを参照してください。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.1 Escape Sequences in String Constants

ダブルクォートされた文字列内では、バックスラッシュ文字は他の文字を表すためのエスケープシーケンスとして使用されます。 In double-quoted strings, the backslash character is used to introduce that represent other characters. たとえば‘\n’はダブルクォートされた文字列内に改行文字を、‘\"’はダブルクォート文字を埋め込みます。シングルクォートされた文字列内では、バックスラッシュ文字は特別な文字ではありません。以下の例は、この違いを示します:

 
toascii ("\n")
    ⇒ 10
toascii ('\n')
    ⇒ [ 92 110 ]

以下は、Octaveで(ダブルクォートされた文字列内で)使用されるすべてのエスケープシーケンスのテーブルです。これらはCプログラミング言語で使用される場合と同じです。

\\

リテラルにバックスラッシュ‘\’を表します。

\"

リテラルのダブルクォート文字‘"’を表します<。

\'

リテラルのシングルクォート文字‘'’を表します。

\0

Null文字(control-@、ASCIIコード0)を表します。

\a

“alert”文字(control-g、ASCIIコード7)を表します。

\b

バックスペース(control-h、ASCIIコード8)を表します。

\f

改ページ(control-l、ASCIIコード12)を表します。

\n

改行(control-j、ASCIIコード10)を表します。

\r

キャリッジリターン(control-m、ASCIIコード13)を表します。

\t

水平タブ(control-i、ASCIIコード9)を表します。

\v

垂直タブ(control-k、ASCIIコード11)を表します。

\nnn

8進値nnnの文字を表します。nnnは0から7の1桁から3桁です。たとえば、アスキーのESC文字は‘\033’です。

\xhh

16進値hhの文字を表します。hhは16進数字(‘0’から‘9’、および‘A’から‘F’または‘a’から‘f’)です。 ANSI-Cの場合と同様、最初の非16進数字が見つかるエスケープシーケンスは継続されます。しかし3桁以上の16進数字は未定義の結果を生成します。

シングルクォートされた文字列内のエスケープシーケンスは、1つだけです。連続してシングルクォート文字を使用することにより、1つのシングルクォート文字を挿入できます。たとえば、

 
'I can''t escape'
    ⇒ I can't escape

スクリプト内では、必要ならis_dq_stringis_sq_stringを使用して、2つの文字列型を区別できます。

Built-in Function: is_dq_string (x)

xがダブルクォートされた文字列の場合は、trueをリターンします。

See also: is_sq_string, ischar.

Built-in Function: is_sq_string (x)

xがシングルクォートされた文字列の場合は、trueをリターンします。

See also: is_dq_string, ischar.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.2 Character Arrays

文字列を表すためにOctaveが使用するのは文字の配列なので、文字列"dddddddddd"は、内部的にはすべての要素が値100(100は"d"のASCIIコード)の長さが10の行ベクターです。これは文字マトリクスにたいする明白な汎化をもたらします。文字マトリクスを使用することにより、同じ長さに文字列コレクションを、1つの変数で表すことが可能になります。Octave内で使用される慣習では、文字マトリクスの各行が個別の文字列になりますが、各列で文字列を表すことも同様に可能です。

文字マトリクスを作成するもっとも簡単な方法は、複数の文字列を一緒にマトリクスに配す方法です。

 
collection = [ "String #1"; "String #2" ];

これは2行9列の文字マトリクスを作成します。

関数ischarは、オブジェクトが文字マトリクスかテストするために使用できます。

Built-in Function: ischar (x)

xが文字配列の場合は、trueをリターンします。

See also: isfloat, isinteger, islogical, isnumeric, iscellstr, isa.

オブジェクトが文字列(例: 文字ベクターか、文字マトリクスでないか、など)なのかテストするためには、以下の例のようにisvector関数を組み合わせてischar関数を使用できます。

 
ischar (collection)
     ⇒ 1

ischar (collection) && isvector (collection)
     ⇒ 0

ischar ("my string") && isvector ("my string")
     ⇒ 1

これに関係して疑問が1つ生じます。異なる長さの文字列から文字マトリクスを作成すると何が起こるでしょうか。短い文字列の最後にOctaveがブランク文字を追加する、というのが答えです。string_fill_char関数を使えば、ブランク文字以外の文字を使うこともできます。

Built-in Function: val = string_fill_char ()
Built-in Function: old_val = string_fill_char (new_val)
Built-in Function: string_fill_char (new_val, "local")

文字マトリクスのすべての行を同じ長さにパディングするために使用される内部変数にたいして、問い合わせまたはセットを行います。これは1文字でなければなりません。デフォルト値は" "(スペース1つ)です。たとえば:

 
string_fill_char ("X");
[ "these"; "are"; "strings" ]
      ⇒  "theseXX"
          "areXXXX"
          "strings"

関数内部から"local"オプションと共に呼び出された場合、変数の変更はその関数または関数のサブルーチンにたいしてローカルになります。関数をexitするときに、変数の元の値がリストアされます。

これは文字マトリクスの問題点を表しています。文字マトリクスでは、長さの異なる文字列の表現は単に不可能なのです。解決策は文字列のセル配列の使用です。これはCell Arrays of Stringsで説明されています。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.3 Creating Strings

文字列を作成するもっとも簡単な方法は、冒頭で紹介したように、テキストをダブルクォートかシングルクォートで囲む方法です。しかし、実際にテキストを記述せずに文字列を作成することも可能です。関数blanksはブランク文字(ASCIIコード32)だけで構成される、与えられた長さの文字列を作成します。

Function File: blanks (n)

n個のブランクからなる文字列をリターンします。

 
blanks (10);
whos ans
     ⇒
      Attr Name        Size                     Bytes  Class
      ==== ====        ====                     =====  =====
           ans         1x10                        10  char

See also: repmat.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.3.1 Concatenating Strings

文字列はマトリクス表記(StringsおよびCharacter Arraysを参照)を使用して作成することができます。これがもっとも自然な方法の場合もあります。たとえば:

 
fullname = [fname ".txt"];
email = ["<" user "@" domain ">"];

どちらの場合も、最終的にどのような文字列になるか容易に判断できます。この方法は、もっとも効率的でもあります。マトリクス結合を使用するとき、パーサーは関数呼び出しと関数による入力の検査というオーバーヘッドなしに、即座に文字列の連結を開始します。

それでも、特定の状況において文字列オブジェクトを連結する関数がいくつかあります: charstrvcatstrcatcstrcatそして最後に一般的な用途のための連結関数が使用できます。horzcatvertcatを参照してください。

Built-in Function: char (x)
Built-in Function: char (x, …)
Built-in Function: char (s1, s2, …)
Built-in Function: char (cell_array)

2つ以上の数値マトリクス、文字マトリクス、セル配列から文字列配列を作成します。引数は垂直に結合されます。リターン値は、文字列配列の各行の文字列が同じ長さになるように、必要に応じブランクでぱっパディングされます。空の入力文字列には意味があり、出力に連結されます。

数値入力では、各要素は対応するASCII文字に変換されます。入力がASCII(0から255)の範囲外の場合、結果はレンジエラーになります。

セル配列では、各要素は個々に連結されます。charにより変換されたセル配列の大部分は、cellstrで元に変換できます。たとえば:

 
char ([97, 98, 99], "", {"98", "99", 100}, "str1", ["ha", "lf"])
   ⇒ ["abc    "
       "       "
       "98     "
       "99     "
       "d      "
       "str1   "
       "half   "]

See also: strvcat, cellstr.

Built-in Function: strvcat (x)
Built-in Function: strvcat (x, …)
Built-in Function: strvcat (s1, s2, …)
Built-in Function: strvcat (cell_array)

2つ以上の数値マトリクス、文字マトリクス、セル配列から文字配列を作成します。。引数は垂直に連結します。リターン値は、文字列配列の各要素が同じ長さになるように、必要に応じブランクでパディングされます。 charと異なり、空文字列は削除され、出力されません

数値入力では、各要素は対応するASCII文字に変換されます。入力がASCII(0から255)の範囲外の場合、結果はレンジエラーになります。

セル配列では、各要素は個々に連結されます。strvcatで変換されたセル配列の大部分は、cellstrで元に変換できます。たとえば:

 
strvcat ([97, 98, 99], "", {"98", "99", 100}, "str1", ["ha", "lf"])
      ⇒ ["abc    "
          "98     "
          "99     "
          "d      "
          "str1   "
          "half   "]

See also: char, strcat, cstrcat.

Function File: strcat (s1, s2, …)

すべての引数を水平に連結した文字列をリターンします。引数がセル文字列の場合、strcatは個々のセルを連結したセル文字列をリターンします。入力が数値の場合、各要素は対応するASCII文字に変換されます。入力文字列の末尾の空白文字は、文字列を連結する前に削除されます。セル文字列にはトリムされた空白文字を含まないことに注意してください。

たとえば:

 
strcat ("|", " leading space is preserved", "|")
    ⇒ | leading space is preserved|
 
strcat ("|", "trailing space is eliminated ", "|")
    ⇒ |trailing space is eliminated|
 
strcat ("homogeneous space |", "  ", "| is also eliminated")
    ⇒ homogeneous space || is also eliminated
 
s = [ "ab"; "cde" ];
strcat (s, s, s)
    ⇒
        "ababab   "
        "cdecdecde"
 
s = { "ab"; "cd " };
strcat (s, s, s)
    ⇒
        {
          [1,1] = ababab
          [2,1] = cd cd cd 
        }

See also: cstrcat, char, strvcat.

Function File: cstrcat (s1, s2, …)

すべての引数を水平に連結した文字列をリターンします。末尾のスペースは残されます。たとえば:

 
cstrcat ("ab   ", "cd")
      ⇒ "ab   cd"
 
s = [ "ab"; "cde" ];
cstrcat (s, s, s)
      ⇒ "ab ab ab "
         "cdecdecde"

See also: strcat, char, strvcat.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.3.2 Converting Numerical Data to Strings

数値データを対応するASCII文字にキャストする文字列連結関数(Concatenating Strings参照)の他にも、数値データを文字列にフォーマットする関数がいくつかあります。mat2strnum2strは実数おとび複素数のマトリクス、int2strは整数マトリクスを変換します。 複素数値にたいしてint2strは、実数部から少数部を整数に丸めて評価します。数値データを文字列にフォーマットする、より柔軟な方法としては、sprintf関数(Formatted Output, sprintf参照)があります。

Function File: s = mat2str (x, n)
Function File: s = mat2str (x, n, "class")

実数、複素数、および論理のマトリクスw文字列としてフォーマットします。リターンされる文字列とeval関数を使用することにより、元のマトリクスを再構築できます。

値の精度は、nにより与えられます。nがスカラーの場合、マトリクスの実数部と虚数部は両方とも同じ精度でプリントされます。スカラーでない場合は、n(1)が実数部の精度、n(2)が虚数部の精度を定義します。nのデフォルト値は15です。

引数"class"が与えられた場合には、evalがそのクラスのマトリクスを構築するときのような方法で、xが文字列結果に含められます。

 
mat2str ([ -1/3 + i/7; 1/3 - i/7 ], [4 2])
     ⇒ "[-0.3333+0.14i;0.3333-0.14i]"

mat2str ([ -1/3 +i/7; 1/3 -i/7 ], [4 2])
     ⇒ "[-0.3333+0i 0+0.14i;0.3333+0i -0-0.14i]"

mat2str (int16 ([1 -1]), "class")
     ⇒ "int16([1 -1])"

mat2str (logical (eye (2)))
     ⇒ "[true false;false true]"

isequal (x, eval (mat2str (x)))
     ⇒ 1

See also: sprintf, num2str, int2str.

Function File: num2str (x)
Function File: num2str (x, precision)
Function File: num2str (x, format)

数字(または配列)を、文字列(または文字配列)に変換します。オプションの第2引数は、出力に使用される有効桁数(precision)、またはsprintf形式(Formatted Output参照)のフォーマット用テンプレート文字列(format)です。num2strは複素数も扱うことができます。

例:

 
num2str (123.456)
     ⇒ "123.46"

num2str (123.456, 4)
     ⇒ "123.5"

s = num2str ([1, 1.34; 3, 3.56], "%5.1f")
     ⇒ s =
        1.0  1.3
        3.0  3.6
whos s
     ⇒
      Attr Name        Size                     Bytes  Class
      ==== ====        ====                     =====  =====
           s           2x8                         16  char

num2str (1.234 + 27.3i)
     ⇒ "1.234+27.3i"

注意:

MATLABとの互換性のため、文字列をリターンする前に先頭のスペースは削除されます。

num2str関数はあまり柔軟ではありません。より柔軟に結果を制御したい場合は、sprintf(Formatted Output参照)を使用してください。

xが複素数の場合は、フォーマット文字列に含める出力変換指定は1つだけにしてください。それ以外では、結果は予測できません。

See also: sprintf, int2str, mat2str.

Function File: int2str (n)

整数(または整数配列)を、文字列(または文字配列)に変換します。

 
int2str (123)
     ⇒ "123"

s = int2str ([1, 2, 3; 4, 5, 6])
     ⇒ s =
        1  2  3
        4  5  6

whos s
     ⇒
      Attr Name        Size                     Bytes  Class
      ==== ====        ====                     =====  =====
           s           2x7                         14  char

この関数はあまり柔軟ではありません。より柔軟に結果を制御したい場合は、sprintf(Formatted Output参照)を使用してください。

See also: sprintf, num2str, mat2str.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4 Comparing Strings

文字列とは文字配列のことなので、以下の例が示すように、文字列は要素ごとに比較されます。

 
GNU = "GNU's Not UNIX";
spaces = (GNU == " ")
     ⇒ spaces =
       0   0   0   0   0   1   0   0   0   1   0   0   0   0

To determine if two strings are identical it is necessary to use the 2つの文字列が等しいか判断するには、strcmp関数を使う必要があります。この関数は大文字小文字を区別して、文字列全体を比較します。strncmpは、最初のN文字だけを比較します(Nはパラメーターとして与えられます)。strcmpistrncmpiは、大文字小文字を区別しません。

Built-in Function: strcmp (s1, s2)

文字列s1s2が同じなら1、それ以外は0をリターンします。

s1s2のいずれかが文字列のセル配列の場合、個々のセル配列にたいして上述した値を含む、セル配列と同じサイズの配列をリターンします。もう一方の引数は文字列のセル配列(同じサイズ、または要素が1つだけのセル配列)、文字マトリクス、または文字列です。

警告: MATLABとの互換性のため、Octaveのstrcmp関数は文字列が等しいときに1、等しくなければ0をリターンします。これは同名のCライブラリー関数とは逆です。

See also: strcmpi, strncmp, strncmpi.

Built-in Function: strncmp (s1, s2, n)

文字列s1s2の最初のn文字が同じなら1、それ以外は0をリターンします。

 
strncmp ("abce", "abcd", 3)
      ⇒ 1

s1s2のいずれかが文字列のセル配列の場合、個々のセル配列にたいして上述した値を含む、セル配列と同じサイズの配列をリターンします。もう一方の引数は文字列のセル配列(同じサイズ、または要素が1つだけのセル配列)、文字マトリクス、または文字列です。

 
strncmp ("abce", {"abcd", "bca", "abc"}, 3)
     ⇒ [1, 0, 1]

警告: MATLABとの互換性のため、Octaveのstrncmp関数は文字列が等しいときに1、等しくなければ0をリターンします。これは同名のCライブラリー関数とは逆です。

See also: strncmpi, strcmp, strcmpi.

Built-in Function: strcmpi (s1, s2)

文字列s1s2が、同じ(大文字小文字の違いは無視)場合は1、それ以外は0をリターンします。

s1s2のいずれかが文字列のセル配列の場合、個々のセル配列にたいして上述した値を含む、セル配列と同じサイズの配列をリターンします。もう一方の引数は文字列のセル配列(同じサイズ、または要素が1つだけのセル配列)、文字マトリクス、または文字列です。

警告: MATLABとの互換性のため、Octaveのstrcmpi関数は文字列が等しいときに1、等しくなければ0をリターンします。これは同名のCライブラリー関数とは逆です。

警告: National alphabetはサポートされません。

See also: strcmp, strncmp, strncmpi.

Built-in Function: strncmpi (s1, s2, n)

s1s2の最初のn文字が同じ(大文字小文字の違いは無視)場合は1、それ以外は0をリターンします。

s1s2のいずれかが文字列のセル配列の場合、個々のセル配列にたいして上述した値を含む、セル配列と同じサイズの配列をリターンします。もう一方の引数は文字列のセル配列(同じサイズ、または要素が1つだけのセル配列)、文字マトリクス、または文字列です。

警告: MATLABとの互換性のため、Octaveのstrncmpi関数は文字列が等しいときに1、等しくなければ0をリターンします。これは同名のCライブラリー関数とは逆です。

警告: National alphabetsはサポートされません。

See also: strncmp, strcmp, strcmpi.

Function File: validstr = validatestring (str, strarray)
Function File: validstr = validatestring (str, strarray, funcname)
Function File: validstr = validatestring (str, strarray, funcname, varname)
Function File: validstr = validatestring (…, position)

strstrarray内の要素、または要素の部分文字列か検証します。

strがテストされる文字列で、strarrayが有効な値となる文字列のセル配列の場合、validstrstrにたいする検証フォームです(検証の定義はstrvalidstrのメンバー、またはメンバーの部分文字列かどうかです)。これはオプションの長い形式が"red"で短い形式が"r"のような場合などに、短い形式を展開して検証するのに便利です。strvalidstrの部分文字列で複数がマッチし、すべてのマッチが部分文字列へのマッチの場合は、最短のマッチがリターンされます。それ以外では、strの展開があいまいなため、エラーがレイズされます。すべての比較で大文字小文字を区別しません。

追加入力のfuncnamevarnamepositionはオプションで、生成される検証エラーメッセージをより具体的にするものです。

例:

 
validatestring ("r", {"red", "green", "blue"})
⇒ "red"

validatestring ("b", {"red", "green", "blue", "black"})
⇒ error: validatestring: multiple unique matches were found for 'b':
   blue, black

See also: strcmp, strcmpi.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.5 Manipulating Strings

Octaveは文字列を操作するための関数を広範にサポートします。文字列は単なるマトリクスなので、単純な操作は標準的な演算子を使用して行うことができます。以下はブランク文字をすべてアンダースコアで置き換える方法を示す例です。

 
quote = ...
  "First things first, but not necessarily in that order";
quote( quote == " " ) = "_"
⇒ quote = 
    First_things_first,_but_not_necessarily_in_that_order

検索、置換、および一般的な正規表現などのより複雑な操作にたいして、Octaveには以下の関数があります。

Function File: deblank (s)

sから末尾の空白文字とnullを削除します。sがマトリクスの場合、deblankは各行をもっとも長い文字列の長さにトリムします。sが文字列のセル配列の場合は、各文字列要素を再帰的に処理します。

例:

 
deblank ("    abc  ")
     ⇒  "    abc"

deblank ([" abc   "; "   def   "])
     ⇒  [" abc  " ; "   def"]

See also: strtrim.

Function File: strtrim (s)

sから先頭と末尾の空白文字を削除します。sがマトリクスの場合、strtrimは各行をもっとも長い文字列の長さにトリムします。sが文字列のセル配列の場合は、各文字列要素を再帰的に処理します。たとえば:

 
strtrim ("    abc  ")
     ⇒  "abc"

strtrim ([" abc   "; "   def   "])
     ⇒  ["abc  "  ; "  def"]

See also: deblank.

Function File: strtrunc (s, n)

文字列sを、長さnに切り詰めます。sが文字マトリクスのは、列数を合わせます。sが文字列のセル配列の場合は、処理は各要素にたいして行われ、新たなセル配列をリターンします。

Function File: findstr (s, t)
Function File: findstr (s, t, overlap)

文字列stの長い方の文字列中で、短い方の文字列が出現するすべての位置をベクターでリターンします。オプション引数overlapがtrueの場合は、リターンされるベクターはオーバーラップする位置を含むことができます(これがデフォルトです)。たとえば:

 
findstr ("ababab", "a")
     ⇒ [1, 3, 5];
findstr ("abababa", "aba", 0)
     ⇒ [1, 5]

警告: findstrは廃止が予定されています。新たなコードはすべてstrfindを使用してください。

See also: strfind, strmatch, strcmp, strncmp, strcmpi, strncmpi, find.

Function File: idx = strchr (str, chars)
Function File: idx = strchr (str, chars, n)
Function File: idx = strchr (str, chars, n, direction)
Function File: [i, j] = strchr (…)

文字列charsから、文字集合charsの文字の出現を検索します。リターン値、および引数のndirectionは、findの場合と同様に振る舞います。

多くの場合、この関数はregexpを使用するより高速です。

See also: find.

Function File: index (s, t)
Function File: index (s, t, direction)

文字列s内で文字列tが最初に出現する位置、見つからない場合は0をリターンします。sには文字列配列、または文字列のセル配列も指定できます。

たとえば:

 
index ("Teststring", "t")
    ⇒ 4

direction"first"の場合は、見つかった最初の要素をリターンします。direction"last"の場合は、見つかった最後の要素をリターンします。

See also: find, rindex.

Function File: rindex (s, t)

文字列s内で文字列tが最後に出現する位置、見つからない場合は0をリターンします。sには文字列配列、または文字列のセル配列も指定できます。

たとえば:

 
rindex ("Teststring", "t")
     ⇒ 6

rindex関数は、direction"last"にセットしたindex関数と等価です。

See also: find, index.

Built-in Function: idx = strfind (str, pattern)
Built-in Function: idx = strfind (cellstr, pattern)
Built-in Function: idx = strfind (…, "overlaps", val)

文字列str内からpatternを検索して、出現の各開始位置のインデクスをベクターidxでリターンします。

パターンが見つからなかった場合、またはpatternstrより長い場合には、idxは空の配列[]になります。オプション引数"overlaps"はパターンがstr内のどの位置でもマッチする(true)か、完全なパターンのユニークな出現だけにマッチする(false)を決定します。デフォルトはtrueです。

文字列のセル配列 cellstrがセットされた場合、idxは上記で指定されたベクターのセル配列になります。

例:

 
strfind ("abababa", "aba")
     ⇒ [1, 3, 5]

strfind ("abababa", "aba", "overlaps", false)
     ⇒ [1, 5]

strfind ({"abababa", "bebebe", "ab"}, "aba")
     ⇒
        {
          [1,1] =

             1   3   5

          [1,2] = [](1x0)
          [1,3] = [](1x0)
        }

See also: findstr, strmatch, regexp, regexpi, find.

Function File: str = strjoin (cstr)
Function File: str = strjoin (cstr, delimiter)

セル文字列配列cstrの要素を1つの文字列に結合します。

delimiterが指定されない場合、cstrの要素の区切りはスペースになります。

delimiterが文字列として指定された場合、その文字列を使用してセル文字列配列が結合されます。エスケープシーケンスもサポートされます。

delimiterがセル文字列配列で、その長さがcstrより1小さい場合は、cstrdelimiterの要素を順番に使って結合されます。エスケープシーケンスはサポートされません。

 
strjoin ({'Octave','Scilab','Lush','Yorick'}, '*')
      ⇒ 'Octave*Scilab*Lush*Yorick'

See also: strsplit.

Function File: strmatch (s, A)
Function File: strmatch (s, A, "exact")

sで始まるAのエントリーのインデクスをリターンします。第2引数Aは文字列、文字マトリクス、または文字列のセル配列でなければなりません。第3引数"exact"が与えられなかった場合、ssの長さまでAに一致するだけでマッチとなります。マッチングでは、sAの末尾のスペースとnullは無視します。

たとえば:

 
strmatch ("apple", "apple juice")
     ⇒ 1

strmatch ("apple", ["apple  "; "apple juice"; "an apple"])
     ⇒ [1; 2]

strmatch ("apple", ["apple  "; "apple juice"; "an apple"], "exact")
     ⇒ [1]

警告: strmatchは廃止が予定されています。 Use strncmp (normal case), or strcmp ("exact" case), or regexp in all new code. See also: strfind, findstr, strcmp, strncmp, strcmpi, strncmpi, find.

Function File: [tok, rem] = strtok (str)
Function File: [tok, rem] = strtok (str, delim)

文字列strから、最初に見つかった文字列delim内の文字(その文字は含まない)までのすべての文字を探します。remが要求された場合、remには最初に見つかった区切り文字から開始する、strの残りの文字列がセットされます。str内の先頭の区切り文字は無視されます。delimが指定されない場合には、スペースが指定されたものとします。strには文字列のセル配列を指定することもでき、その場合は個々の文字列にたいして関数が実行され、見つかったトークンと残りの文字がセル配列でリターンされます。

例:

 
strtok ("this is the life")
     ⇒ "this"

[tok, rem] = strtok ("14*27+31", "+-*/")
     ⇒
        tok = 14
        rem = *27+31

See also: index, strsplit, strchr, isspace.

Function File: [cstr] = strsplit (s)
Function File: [cstr] = strsplit (s, del)
Function File: [cstr] = strsplit (…, name, value)
Function File: [cstr, matches] = strsplit (…)

delで指定された区切り文字を使用して文字列sを分割し、分割された部分文字列のセル文字列配列をリターンします。区切り文字が指定されない場合、文字列sは空白文字で分割されます。区切り文字delには文字列、スカラーのセル文字列、またはセル文字列配列を指定できます。デフォルトでは入力文字列s内の連続する区切り文字は、1つにまとめられます。

第2出力matchesには元文字列内でマッチした区切り文字がリターンされます。

例:

 
strsplit ("a b c")
      ⇒
          {
            [1,1] = a
            [1,2] = b
            [1,3] = c
          }

strsplit ("a,b,c", ",")
      ⇒
          {
            [1,1] = a
            [1,2] = b
            [1,3] = c
          }

strsplit ("a foo b,bar c", {"\s", "foo", "bar"})
      ⇒
          {
            [1,1] = a
            [1,2] = b
            [1,3] = c
          }

strsplit ("a,,b, c", {",", " "}, false)
      ⇒
          {
            [1,1] = a
            [1,2] = 
            [1,3] = b
            [1,4] = 
            [1,5] = c
          }

サポートされるname/valueペアー引数は;

例:

 
strsplit ("a foo b,bar c", ",|\\s|foo|bar", "delimitertype", "regularexpression")
      ⇒
          {
            [1,1] = a
            [1,2] = b
            [1,3] = c
          }

strsplit ("a,,b, c", "[, ]", false, "delimitertype", "regularexpression")
      ⇒
          {
            [1,1] = a
            [1,2] = 
            [1,3] = b
            [1,4] = 
            [1,5] = c
          }

strsplit ("a,\t,b, c", {',', '\s'}, "delimitertype", "regularexpression")
      ⇒
          {
            [1,1] = a
            [1,2] = b
            [1,3] = c
          }

strsplit ("a,\t,b, c", {',', ' ', '\t'}, "collapsedelimiters", false)
      ⇒
          {
            [1,1] = a
            [1,2] = 
            [1,3] = 
            [1,4] = b
            [1,5] = 
            [1,6] = c
          }

See also: ostrsplit, strjoin, strtok, regexp.

Function File: [cstr] = ostrsplit (s, sep)
Function File: [cstr] = ostrsplit (s, sep, strip_empty)

文字列sを1つ以上のセパレーターsepで分割して、文字列のセル配列をリターンします。strip_emptyがtrueでない場合、連続するセパレーター、および境界のセパレーターは、空文字列の結果になります。strip_emptyのデフォルト値はfalseです。

2次元文字配列はセパレーター、および元々の列境界で分割されます。

例:

 
ostrsplit ("a,b,c", ",")
      ⇒
          {
            [1,1] = a
            [1,2] = b
            [1,3] = c
          }

ostrsplit (["a,b" ; "cde"], ",")
      ⇒
          {
            [1,1] = a
            [1,2] = b
            [1,3] = cde
          }

See also: strsplit, strtok.

Function File: [a, …] = strread (str)
Function File: [a, …] = strread (str, format)
Function File: [a, …] = strread (str, format, format_repeat)
Function File: [a, …] = strread (str, format, prop1, value1, …)
Function File: [a, …] = strread (str, format, format_repeat, prop1, value1, …)

文字列からデータを読み取ります。

文字列strは、formatの指定に順繰りにマッチする単語に分割されます。つまり、最初の単語は1つ目の指定、次の単語は2つ目の指定にたいするマッチ、のようにとなります。指定子より多くの単語がある場合には、すべての単語が処理されるまで、このプロセスが繰り返されます。

文字列formatには、str内で単語がパースされる方法を記述します。これには以下の指定の任意の組み合わせが含まれます:

%s

単語は文字列としてパースされる。

%f
%n

単語は数字としてパースされ、倍精度に変換される。

%d
%u

単語は数字としてパースされ、int32に変換される。

%*', '%*f', '%*s

単語をスキップする。

%sと%d、%f、%n、%uおよび関連する%*s …は、%N(Nは2以上の整数)によるオプションの幅指定です。%fにたいしては、%N.Mfのような指定ができます。

literals

これらに加え、フォーマットにはリテラル文字列が含まれる場合があり、これらは読み込みの際にはスキップされます。

パースされた単語は、1つ目の指定子に対応する単語は1つ目の出力引数にリターンされ、残りの指定子も同様です。

formatのデフォルトは"%f"で、これはstrから数字が読み取られることを意味します。これはstrに数値フィールドが含まれるときだけ行われます。

たとえば、文字列

 
str = "\
Bunny Bugs   5.5\n\
Duck Daffy  -7.5e-5\n\
Penguin Tux   6"

は、以下で読み取ることができます

 
[a, b, c] = strread (str, "%s %s %f");

オプションの数値引数format_repeatは、読み取るアイテム数を制限するために使用できます:

-1

すべての文字列を最後まで読み取る。

N

nargoutアイテムをN回読み込みます。format_repeatには0を指定することもできます。

プロパティー値ペアーを使って、strreadの挙動を変更できます。以下のプロパティが認識されます:

"commentstyle"

strのパーツはコメントと判断され、スキップされる。valueはコメントスタイルで、以下を使用できます。

  • "shell" #文字から行末までのすべてがスキップされる。
  • "c" /**/の間のすべてがスキップされる。
  • "c++" //文字から行末までのすべてがスキップされる。
  • "matlab" %文字から行末までのすべてがスキップされる。
  • ユーザー指定。オプションは2つ (1) 1つの文字列、また1x1のセル文字列: この右側のすべてがスキップされる; (2) 2x1のセル文字列配列: 左側の文字列と右側の文字列の間のすべてがスキップされる。
"delimiter"

value内の文字は、strを単語に分割するために使用される(デフォルト値は任意の空白文字)。

"emptyvalue":

非空白文字で区切られた空の数値にたいしてリターンする値。デフォルトはNaN。そのデータ型がNaNをサポートしない場合(たとえばint32)のデフォルトは0。

"multipledelimsasone"

間に空白文字がない連続する区切り文字のシリーズを、1つの区切り文字として扱う。連続する区切り文字シリーズは垂直に"aligned"(整列されている)必要はない。

"treatasempty"

value内の(区切り文字か空白文字で囲まれた)文字列が1つあったら、それを欠損値として扱う。

"returnonerror"

valueがtrue(デフォルトは1)の場合は、読み取りエラーを無視して通常どおりリターンする。false(0)の場合は、エラーをリターンする。

"whitespace"

value内の任意の文字は空白文字と解釈され、トリムされる。/tのような特殊文字を正しく処理するために、ダブルクォートで囲まなければならない。空白文字のデフォルト値は" brnt"(スペースが含まれることにに注意)。空白文字が”(空)にセットされておらず"%s"フォーマット変更指定子が1つも指定されていない場合、スペースは常に空白文字の一部となる。

str内の単語数がフォーマット変換指定子の数に正確にマッチしない、strreadの振る舞いはstrの最後の文字に依存する:

最後の文字 = "n"

データ列は空フィールドかNaNでパディングされるので、すべての列が同じ長さになる

最後の文字がt "n"以外

データ列はパディングされない。strreadは長さが異なる列をリターンする

See also: textscan, textread, load, dlmread, fscanf.

Built-in Function: newstr = strrep (str, ptn, rep)
Built-in Function: newstr = strrep (cellstr, ptn, rep)
Built-in Function: newstr = strrep (…, "overlaps", val)

文字列str内にあるすべてのパターンptnを文字列repで置換して、その結果をリターンします。

オプション引数"overlaps"は、パターンがstr内のすべての位置でマッチできる(true)か、それとも完全なパターンの一意な出現だけにマッチできるかを決定します。デフォルトはtrueです。

sには文字列のセル配列も指定でき、その場合は各要素にたいして置換が行われ、セル配列がリターンされます。

例:

 
strrep ("This is a test string", "is", "&%$")
    ⇒  "Th&%$ &%$ a test string"

See also: regexprep, strfind, findstr.

Function File: substr (s, offset)
Function File: substr (s, offset, len)

文字位置offsetから始まる長さlen文字の一部文字列をリターンします。

オフセット位置の番号は1から開始されます。offsetが負の場合は、抽出開始位置は文字列の終端からのオフセットで数えられます。

lenが省略された場合、一部文字列はSの終端まで拡張されます。lenに負の値を指定すると、文字列の最後のlen文字が抽出されます。

例:

 
substr ("This is a test string", 6, 9)
     ⇒ "is a test"
substr ("This is a test string", -11)
     ⇒ "test string"
substr ("This is a test string", -11, -7)
     ⇒ "test"

この関数はPerlの同名の関数を元にしています。

Built-in Function: [s, e, te, m, t, nm, sp] = regexp (str, pat)
Built-in Function: […] = regexp (str, pat, "opt1", …)

文字列をマッチングするための正規表現です。strからpatを検索して、マッチした位置と部分文字列、マッチしなかったときは空の値をリターンします。

マッチさせるパターンpatには以下の標準的なregex演算子が含まれます:

.

任意の文字にマッチする

* + ? {}

繰り返し演算子。以下の意味をもつ

*

0回以上のマッチ

+

1回以上のマッチ

?

0または1回のマッチ

{n}

正確にn回のマッチ

{n,}

n回以上のマッチ

{m,n}

m回からn回のマッチ

[…] [^…]

リスト演算子。パターンは"["と"]"の間にリストされた任意の文字にマッチする。最初の文字が"^"の場合、パターンの意味は逆になり、角カッコの間にリストされた文字以外の任意の文字にマッチする。

リスト演算子内で以下で定義されるエスケープシーケンスを使用できる。たとえば浮動小数点数にたいするテンプレートは[-+.\d]+のようになる。

() (?:)

グループ化演算子。1つ目の丸カッコだけの形式はトークンも作成する。

|

選択肢のための演算子。正規表現からなる選択肢の1つにマッチする。選択肢は上述のグループ化演算子()で区切らなければならない。

^ $

アンカー演算子。文字列の開始、または終了を示すには、(^)および($)のパターンが要求される。

さらに以下のエスケープシーケンスは、特別な意味をもつ。

\d

任意の数字にマッチする

\D

数字以外の任意の文字にマッチする

\s

任意の空白文字にマッチする

\S

空白文字以外の任意の文字にマッチする

\w

任意の単語文字にマッチする

\W

単語以外の任意の文字にマッチする

\<

単語の先頭にマッチする

\>

単語の末尾にマッチする

\B

単語の内部にマッチする

実装ノート: MATLABとの互換性のため、通常のエスケープシーケンス(例: "n" => newline)は、patがシングルクォートで定義されているか否かに関わらず処理されます。エスケープシーケンスの補間を停止するには2つ目のバックスラッシュ(例: "\\n")を使うか、regexptranslate関数を使用してください。

regexpのデフォルトの出力順は以下で与えられます

s

マッチした部分文字列の開始インデクス

e

マッチした部分文字列の終了インデクス

te

マッチした各トークンをpat内の(…)で囲んだものの範囲

m

各マッチのテキストのセル配列

t

各マッチのトークンのテキストのセル配列

nm

マッチした名前付きトークン(名前はフィールド名として使用される)のテキストを含む構造体。名前付きトークンは(?<name>…)で表される。

sp

テキストのセル配列(例: patにより文字列を分割したときの残り)はマッチによりリターンされない。

特定の出力引数、または出力引数の順番は、追加の引数optで選択できます。これらは文字列で、出力引数とオプション引数の対応は以下のとおりです

'start's
'end'e
'tokenExtents'te
'match'm
'tokens't
'names'nm
'split'sp

追加の引数を以下に要約します。

once

パターンの最初の出現だけをリターンする。

matchcase

大文字小文字を区別せずにマッチングする(デフォルト)。

パターン内で(?-i)を使用して代替できる。

ignorecase

大文字小文字を区別してマッチングする。

パターン内で(?i)を使用して代替できる。

stringanchors

アンカー文字は文字列の開始と終了にマッチする(デフォルト)。

パターン内で(?-m)を使用して代替できる。

lineanchors

アンカー文字は行の開始と終了にマッチする(デフォルト)。

パターン内で(?m)を使用して代替できる。

dotall

パターン.は、改行文字を含むすべての文字にマッチする(デフォルト)。

パターン内で(?s)を使用して代替できる。

dotexceptnewline

パターン.は、改行文字を除くすべての文字にマッチする。

パターン内で(?-s)を使用して代替できる。

literalspacing

空白文字を含む、パターン内のすべての文字は有意であり、パターンマッチングに使用される(デフォルト)。

パターン内で(?-x)を使用して代替できる。

freespacing

パターンは任意の空白文字、および文字‘#’で始まるコメントを含むことができる。

パターン内で(?x)を使用して代替できる。

noemptymatch

長さ0のマッチはリターンされない(デフォルト)。

emptymatch

長さ0のマッチをリターンする。

regexp ('a', 'b*', 'emptymatch')[1 2]をリターンする。それは0文字以上の'b'が位置1と文字列終端にマッチするからである。

See also: regexpi, strfind, regexprep.

Built-in Function: [s, e, te, m, t, nm, sp] = regexpi (str, pat)
Built-in Function: […] = regexpi (str, pat, "opt1", …)

大文字小文字を区別せずに正規表現による文字列マッチングを行います。str内からpatを検索して、マッチした位置と部分文字列、マッチしなかったときは空の値をリターンします。検索パターン構文の詳細は、regexpを参照してください。

See also: regexp.

Built-in Function: outstr = regexprep (string, pat, repstr)
Built-in Function: outstr = regexprep (string, pat, repstr, "opt1", …)

string内に存在するパターンpatを、repstrで置き換えます。

パターンはregexpに記述されている正規表現です。regexpを参照してください。

置換文字列には$iを含めることができます。これはマッチした文字列内の、i番目のカッコで括られたもので置換されます。たとえば、

 
regexprep ("Bill Dunn", '(\w+) (\w+)', '$2, $1')

は、"Dunn, Bill"をリターンします

追加オプションはregexpのものに以下が加わります

once

結果の中の最初にあったregexpだけを置換する。

warnings

このオプションは互換性のためだけで、無視される。

実装ノート: MATLABとの互換性のためpatrepstr内のエスケープシーケンス(例: "n" => 改行)は、それらがシングルクォート内で定義されているか否かに関わらず、通常どおり処理されます。エスケープシーケンスの補間を防ぐには2つ目のバックスラッシュを使かう(例: "\\n")か、regexptranslate関数を使用してください。

See also: regexp, regexpi, strrep.

Function File: regexptranslate (op, s)

正規表現として使用するために文字列を翻訳します。これにはワイルドカードの置換や、特殊文字のエスケープが含まれます。この振る舞いはopにより制御され、以下の値をとることができます

"wildcard"

ワイルドカード文字.*?は適切な正規表現に置き換えられます。たとえば:

 
regexptranslate ("wildcard", "*.m")
     ⇒ ".*\.m"
"escape"

文字$.?[]は正規表現では特別な意味をもつので、リテラルとして扱うためには、エスケープする必要があります。たとえば:

 
regexptranslate ("escape", "12.5")
     ⇒ "12\.5"

See also: regexp, regexpi, regexprep.

Function File: untabify (t)
Function File: untabify (t, tw)
Function File: untabify (t, tw, deblank)

t内のTAB文字を、スペースで置き換えます。TAB幅はtwでの指定、またはデフォルトの8になります。入力のtは2次元文字配列、または文字列のセル配列です。出力は入力と同じクラスになります。

オプション引数deblankがtrueの場合、文字データの末尾のスペースは削除されます。

以下は、ファイルを読み込んでから、最後のス同じファイルのスペースを取り除いた、TABなしバージョンを書き込む例です。

 
fid = fopen ("tabbed_script.m");
text = char (fread (fid, "uchar")');
fclose (fid);
fid = fopen ("untabified_script.m", "w");
text = untabify (strsplit (text, "\n"), 8, true);
fprintf (fid, "%s\n", text{:});
fclose (fid);

See also: strjust, strsplit, deblank.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.6 String Conversions

Octaveは文字列と数値の間で、さまざまな種類の変換をサポートします。1例をあげると、16進数を含む文字列を、浮動小数点数に変換することができます。

 
hex2dec ("FF")
      ⇒ 255

Function File: bin2dec (s)

文字列sで表された2進数に対応する10進数をリターンします。たとえば:

 
bin2dec ("1110")
     ⇒ 14

変換において、2進数値のかどくせいを工場させるために使用されるかもしれないスペースは無視されます。

 
bin2dec ("1000 0001")
     ⇒ 129

sが文字列マトリクスの場合は、sの行ごとに1つの数値に変換した列ベクターをリターンします。無効な行はNaNに評価されます。

sが文字列のセル配列の場合は、s内のセル要素ごとに1つの数値に変換した列ベクターをリターンします。

See also: dec2bin, base2dec, hex2dec.

Function File: dec2bin (d, len)

非負の整数dに大王する2進数値を、1と0からなる文字列でリターンします。たとえば:

 
dec2bin (14)
     ⇒ "1110"

dがマトリクスまたはセル配列の場合は、d内の要素ごとに1行(最大値の幅になるように先頭に0がパディングされます)となる文字列マトリクスをリターンします。

2つ目のオプション引数lenは、結果の最小の桁数を指定します。

See also: bin2dec, dec2base, dec2hex.

Function File: dec2hex (d, len)

非負の整数dに対応する16進文字列をリターンします。たとえば:

 
dec2hex (2748)
     ⇒ "ABC"

dがマトリクスまたはセル配列の場合は、d内の要素ごとに1行(最大値の幅になるように先頭に0がパディングされます)となる文字列マトリクスをリターンします。

2つ目のオプション引数lenは、結果の最小の桁数を指定します。

See also: hex2dec, dec2base, dec2bin.

Function File: hex2dec (s)

文字列sで表された16進数値に対応する整数をリターンします。たとえば:

 
hex2dec ("12B")
      ⇒ 299
hex2dec ("12b")
      ⇒ 299

sが文字列マトリクスの場合は、sの行ごとに1つの数値に変換した列ベクターをリターンします。無効な行はNaNに評価されます。

sがセル配列の場合は、s内のセル要素ごとに1つの数値に変換された列ベクターをリターンします。

See also: dec2hex, base2dec, bin2dec.

Function File: dec2base (d, base)
Function File: dec2base (d, base, len)

非負の整数dに対応する、基数baseのシンボル文字列をリターンします。

 
dec2base (123, 3)
   ⇒ "11120"

dがマトリクスまたはセル配列の場合は、d内の要素ごとに1行(最大値の幅になるように先頭に0がパディングされます)となる文字列マトリクスをリターンします。

baseが文字列の場合は、baseの文字がdの桁のシンボルとして使用されます。スペース(’ ’)はシンボルとして使用されません。

 
dec2base (123, "aei")
   ⇒ "eeeia"

3つ目のオプション引数lenは、結果の最小の桁数を指定します。

See also: base2dec, dec2bin, dec2hex.

Function File: base2dec (s, base)

基数baseの数字文字列を10進整数(基数10)に変換します。

 
base2dec ("11120", 3)
   ⇒ 123

sが文字列マトリクスの場合は、sの各行が1つの値になる列ベクターをリターンします。行に無効なシンボルが含まれる場合、対応する値はNaNになります。

sが文字列のセル配列の場合は、s内のセル要素ごとに1つの値となる列ベクターをリターンします。

baseが文字列の場合は、baseの文字がsの数字のシンボルとして使用されます。スペース(’ ’)はシンボルとして使用されません。

 
base2dec ("yyyzx", "xyz")
   ⇒ 123

See also: dec2base, bin2dec, hex2dec.

Built-in Function: s = num2hex (n)

倍精度または単精度数値のベクターを、IEEE 754数値表現の8文字または16文字の16進文字列に型キャストします。たとえば:

 
num2hex ([-1, 1, e, Inf])
⇒ "bff0000000000000
    3ff0000000000000
    4005bf0a8b145769
    7ff0000000000000"

引数nが単精度数値の数値またはベクターの場合、リターンされる文字列の長さは8になります。たとえば:

 
num2hex (single ([-1, 1, e, Inf]))
⇒ "bf800000
    3f800000
    402df854
    7f800000"

See also: hex2num, hex2dec, dec2hex.

Built-in Function: n = hex2num (s)
Built-in Function: n = hex2num (s, class)

16文字16進文字列を、IEEE 754の倍精度数値に型キャストします。与えられた文字列が16文字未満の場合は、右に文字'0'がパディングされます。

文字列マトリクスが与えられた場合、hex2numは各行を個別の数値として扱います。

 
hex2num (["4005bf0a8b145769"; "4024000000000000"])
   ⇒ [2.7183; 10.000]

オプション引数classにはもっと"single"を渡すことができ、これは与えられた文字列を単精度数値として解釈すべきことを指定します。この場合、sは8文字の16進文字列になります。たとえば:

 
hex2num (["402df854"; "41200000"], "single")
   ⇒ [2.7183; 10.000]

See also: num2hex, hex2dec, dec2hex.

Built-in Function: str2double (s)

文字列を実数または複素数に変換します。

文字列は以下のフォーマットのうちの1つでなければなりません。ここでaとbは実数、複素数単位は'i''j'です。

もし与えられた場合、aおよび/またはbは[+-]d[,.]d[[eE][+-]d]という形式です。ここで角カッコはオプション引数を示し、'd'は0以上の数字を示します。特別な入力値InfNaNNAも指定できます。

sは文字列、文字マトリクス、またはセル配列です。文字列配列にたいしては、各行にたいして変換が繰り返され、倍精度または複素数の配列がリターンされます。s内の空行は削除され、数値配列はリターンされません。セル配列にたいしては各文字列要素が処理され、sと同じ次元の倍精度または複素数の配列がリターンされます。

互換性のないスカラーまたは文字列が入力された場合、str2doubleはNaNをリターンします。同様に文字配列が入力された場合、str2doubleは変換できなかったsの行にNaNをリターンします。セル配列にたいして、str2doubleは変換がに失敗したsの要素にたいしてNaNをリターンします。文字列と数値が混交されたセル配列内の数値要素は文字列ではないので、これらの要素の変換は失敗しNaNがリターンされることに注意してください。

str2doublestr2numに置き換えることができ、未知のデータにたいしてevalを使用するセキュリティリスクを避けます。

See also: str2num.

Function File: strjust (s)
Function File: strjust (s, pos)

pos("left""center"、または"right")に応じてsを整列したテキストをリターンします。posが省略された場合、デフォルトは"right"です。

null文字はスペースに置き換えられます。それ以外のすべての文字は、非空白文字として扱います。

例:

 
strjust (["a"; "ab"; "abc"; "abcd"])
     ⇒
        "   a"
        "  ab"
        " abc"
        "abcd"

See also: deblank, strrep, strtrim, untabify.

Function File: x = str2num (s)
Function File: [x, state] = str2num (s)

文字列(または文字配列)sを数値(または配列)に変換します。たとえば:

 
str2num ("3.141596")
      ⇒ 3.141596

str2num (["1, 2, 3"; "4, 5, 6"])
      ⇒ 1  2  3
         4  5  6

2つ目のオプション出力stateは、変換が成功したときは論理的trueになります。変換が失敗した場合、数値出力は空で、stateはfalseになります。

警告: str2numは変換を行うためにeval関数を使用しているので、文字列sに含まれる任意のコードは実行されます。より安全かつ高速な変換のためにstr2doubleを使用してください。

文字列のセル配列には、str2doubleを使用してください。

See also: str2double, eval.

Mapping Function: toascii (s)

sのASCII表現をマトリクスでリターンします。たとえば:

 
toascii ("ASCII")
     ⇒ [ 65, 83, 67, 73, 73 ]

See also: char.

Mapping Function: tolower (s)
Mapping Function: lower (s)

文字列またはセル文字列sの大文字を対応する小文字に置き換えたコピーをリターンします。非アルファベット文字は変更されません。たとえば:

 
tolower ("MiXeD cAsE 123")
      ⇒ "mixed case 123"

See also: toupper.

Mapping Function: toupper (s)
Mapping Function: upper (s)

文字列またはセル文字列sの小文字を対応する大文字に置き換えたコピーをリターンします。非アルファベット文字は変更されません。たとえば:

 
toupper ("MiXeD cAsE 123")
      ⇒ "MIXED CASE 123"

See also: tolower.

Built-in Function: do_string_escapes (string)

string内のエスケープされた特殊文字を、特殊文字にに変換します。

Built-in Function: undo_string_escapes (s)

文字列内の特殊文字を、エスケープされた形式に変換します。たとえば、

 
bell = "\a";

この式は変数bellにalert文字(control-g、ASCIIコード7)を割り当てます。この文字列がプリントされた場合、(もし可能なら)システムは端末ベルを鳴らすでしょう。通常これは望んだ結果です。しかし特殊文字をエスケープシーケンスに置き換えて、元の文字列表現をプリントできたほうが便利な場合もあります。たとえば、

 
octave:13> undo_string_escapes (bell)
ans = \a

これはプリントできないalert文字を、プリント可能な表現に置き換えます。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.7 Character Class Functions

Octaveは以下のような、C標準ライブラリーに倣った文字クラステスト関数も提供します。これらはすべて文字列配列を処理して、0と1からなるマトリクスをリターンします。非0の要素は文字列配列内の対応する文字がtrueであることを示します。たとえば:

 
isalpha ("!Q@WERT^Y&")
     ⇒ [ 0, 1, 0, 1, 1, 1, 1, 0, 1, 0 ]

Mapping Function: isalnum (s)

sの要素が英数字ならtrue、それ以外はfalseのような論理配列をリターンします。この関数は(isalpha (s) | isdigit (s))と等価です。

See also: isalpha, isdigit, ispunct, isspace, iscntrl.

Mapping Function: isalpha (s)

sの要素がアルファベットならtrue、それ以外はfalseのような論理配列をリターンします。この関数は(islower (s) | isupper (s))と等価です。

See also: isdigit, ispunct, isspace, iscntrl, isalnum, islower, isupper.

Function File: isletter (s)

sの要素がアルファベットならtrue、それ以外はfalseのような論理配列をリターンします。この関数はisalpha関数のエイリアスです。

See also: isalpha, isdigit, ispunct, isspace, iscntrl, isalnum.

Mapping Function: islower (s)

sの要素がアルファベット小文字ならtrue、それ以外はfalseのような論理配列をリターンします。

See also: isupper, isalpha, isletter, isalnum.

Mapping Function: isupper (s)

sの要素がアルファベット大文字ならtrue、それ以外はfalseのような論理配列をリターンします。

See also: islower, isalpha, isletter, isalnum.

Mapping Function: isdigit (s)

sの要素が10進数字(0-9)ならtrue、それ以外はfalseのような論理配列をリターンします。

See also: isxdigit, isalpha, isletter, ispunct, isspace, iscntrl.

Mapping Function: isxdigit (s)

sの要素が16進数字(0-9およびa-fA-F)ならtrueのような論理配列をリターンします。

See also: isdigit.

Mapping Function: ispunct (s)

sの要素が句読点文字ならtrue、それ以外はfalseのような論理配列をリターンします。

See also: isalpha, isdigit, isspace, iscntrl.

Mapping Function: isspace (s)

sの要素が空白文字(スペース、改ページ、改行、復帰、タブ、垂直タブ)ならtrue、それ以外はfalseのような論理配列をリターンします。

See also: iscntrl, ispunct, isalpha, isdigit.

Mapping Function: iscntrl (s)

sの要素がコントロール文字ならtrue、それ以外はfalseのような論理配列をリターンします。

See also: ispunct, isspace, isalpha, isdigit.

Mapping Function: isgraph (s)

sの要素がプリント可能文字(ただしスペース以外)ならtrue、それ以外はfalseのような論理配列をリターンします。

See also: isprint.

Mapping Function: isprint (s)

sの要素がプリント可能文字(スペース文字も含む)ならtrue、それ以外はfalseのような論理配列をリターンします。

See also: isgraph.

Mapping Function: isascii (s)

sの要素がASCII文字(10進の0から127)ならtrue、それ以外はfalseのような論理配列をリターンします。

Function File: isstrprop (str, prop)

文字列プロパティをテストします。たとえば:

 
isstrprop ("abc123", "alpha")
⇒ [1, 1, 1, 0, 0, 0]

strがセル配列の場合は、セル配列の各要素にたいしてisstrpopが再帰的に適用されます。

数値配列は文字列に変換されます。

2つ目の引数propは、以下のうちの1つでなければなりません

"alpha"

文字がアルファベットならtrue。

"alnum"
"alphanum"

文字が英数字ならtrue。

"lower"

アルファベット小文字ならtrue。

"upper"

アルファベット大文字ならtrue。

"digit"

10進数字(0-9)ならtrue。

"xdigit"

16進数字(a-fA-F0-9)ならtrue。

"space"
"wspace"

空白文字(スペース、改ページ、改行、復帰、タブ、垂直タブ)ならtrue。

"punct"

句読点文字(スペース、英数字を除くプリント文字)ならtrue。

"cntrl"

コントロール文字ならtrue。

"graph"
"graphic"

スペース以外のプリント文字ならtrue。

"print"

スペースを含むプリント文字ならtrue。

"ascii"

ASCIIエンコーディング範囲内の文字ならtrue。

See also: isalpha, isalnum, islower, isupper, isdigit, isxdigit, isspace, ispunct, iscntrl, isgraph, isprint, isascii.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6. Data Containers

Octaveには、任意のデータ型を同じ変数に含めるために、2つの異なるメカニズムをサポートします。Cスタイルの構造体は名前付きフィールドでインデクスされ、セル配列は配列の各要素が異なるデータ型と形状をもつことができます。関数の複数の入力引数やリターン値は、カンマ区切りリストという他のデータ型により形成されます。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.1 Structures

Octaveには構造体内のデータを組織化するためのサポートが含まれます。現在の実装は文字列によるインデクスに限定された連想配列を使用しますが、Cスタイルの構造体に類似した構文です。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.1.1 Basic Usage and Examples

以下はOctaveでデータ構造体を使用する例です。

構造体の要素には任意の値型を使用できます。たとえば

 
x.a = 1;
x.b = [1, 2; 3, 4];
x.c = "string";

この3つの式は、要素が3つの構造体を作成します。文字‘.’は構造体名とィールド名を区別し、Octaveにたいしてこれが構造体であることを示します。他の変数と同様に構造体の名前をタイプすれば、構造体の値をプリントできます。

 
x
     ⇒ x =
        {
          a = 1
          b =

            1  2
            3  4

          c = string
        }

Octaveは任意の順序で要素をプリントすることに注意してください。

他の変数と同じように、構造体をコピーできます。

 
y = x
     ⇒ y =
        {
          a = 1
          b =

            1  2
            3  4

          c = string
        }

構造体はそれ自体が値なので、構造体の要素が他の構造体を参照することもあります。以下の命令文は構造体xの要素bの値を、値が3であるような1つの要素dをもつデータ構造体に変更します。

 
x.b.d = 3;
x.b
     ⇒ ans =
        {
          d = 3
        }

x
     ⇒ x =
        {
          a = 1
          b =
          {
            d = 3
          }

          c = string
        }

構造体が他の構造体を含むとき、Octaveはそれらの2、3レベルだけをプリントすることに注意してください。たとえば:

 
a.b.c.d.e = 1;
a
     ⇒ a =
        {
          b =
          {
            c =
            {
              1x1 struct array containing the fields:

              d: 1x1 struct
            }
          }
        }

これは、大きくネストが深い構造体による、長く混乱した出力を抑制するためです。ネストされた構造体にたいしてプリントするレベル数は、関数struct_levels_to_printでセットすることができ、構造体配列の内容のプリントを有効にするには関数print_struct_array_contentsが使用されます。

Built-in Function: val = struct_levels_to_print ()
Built-in Function: old_val = struct_levels_to_print (new_val)
Built-in Function: struct_levels_to_print (new_val, "local")

表示する構造体レベル数を指定する内部変数にたいして、問い合わせまたはセットをします。

関数の内部で"local"オプションとともに呼び出された場合、変数の変更はその関数および関数のサブルーチンにたいしてローカルになります。関数をexitするとき、変数の元の値がリストアされます。

See also: print_struct_array_contents.

Built-in Function: val = print_struct_array_contents ()
Built-in Function: old_val = print_struct_array_contents (new_val)
Built-in Function: print_struct_array_contents (new_val, "local")

構造体配列の内容をプリントするかどうかを指定する内部変数にたいして、問い合わせまたはセットを行います。

trueの場合、構造体配列の要素はプリントされます。この変数は、要素が常にプリントされるスカラー構造体には影響しません。しかしどちらの場合も、プリントされるのはstruct_levels_to_printで指定されるレベル数に制限されます。

関数の内部で"local"とともに呼び出された場合、変数の変更はその関数および関数のサブルーチンにたいしてローカルになります。関数をexitするときに、変数の元の値がリストアされます。

See also: struct_levels_to_print.

関数は構造体をリターンすることができます。たとえば、以下の関数はマトリクスの実数部と複素部を分割して、同じ構造体変数の2つの要素に格納します。

 
function y = f (x)
  y.re = real (x);
  y.im = imag (x);
endfunction

複素数値を引数に呼び出された場合、fは元の関数引数の実数部と虚数部を含むデータ構造体をリターンします。

 
f (rand (2) + rand (2) * I)
     ⇒ ans =
        {
          im =

            0.26475  0.14828
            0.18436  0.83669

          re =

            0.040239  0.242160
            0.238081  0.402523

        }

リストをリターンする関数には構造体要素を含めることができ、それらは他の変数と同じようにインデクスされます。たとえば:

 
[ x.u, x.s(2:3,2:3), x.v ] = svd ([1, 2; 3, 4]);
x
     ⇒ x =
        {
          u =

            -0.40455  -0.91451
            -0.91451   0.40455

          s =

             0.00000   0.00000   0.00000
             0.00000   5.46499   0.00000
             0.00000   0.00000   0.36597

          v =

            -0.57605   0.81742
            -0.81742  -0.57605

        }

for命令の特別フォームを使用して、構造体のすべての要素を巡回することも可能です(Looping Over Structure Elementsを参照)。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.1.2 Structure Arrays

構造体配列とは、構造体の各フィールドがセル配列で表される、構造体固有のインスタンスです。 これらの各セル配列は同じ次元をもちます。概念上、構造体配列は同じフィールドをもつ構造体の配列と捉えることもできます。以下は構造体配列を作成する例です

 
x(1).a = "string1";
x(2).a = "string2";
x(1).b = 1;
x(2).b = 2;

これは2つのフィールドをもつ2×1の構造体配列を作成しています。構造体配列を作成する別の方法として、struct関数があります(Creating Structuresを参照)。すでに示したように、名前をタイプすることにより、構造体配列の値をプリントできます。

 
x
     ⇒ x =
        {
          1x2 struct array containing the fields:

            a
            b
        }  

構造体配列の各要素はx(1)のようにインデクス付された変数でリターンされ、この変数は2つのフィールドをもつ構造体をリターンします:

 
x(1)
     ⇒ ans =
        {
          a = string1
          b =  1
        }

さらに構造体配列は、それがフィールド名でインデクス付けされている場合は、フィールド値のカンマ区切りリストをリターンします(Comma Separated Listsを参照)。

 
x.a
     ⇒
        ans = string1
        ans = string2

以下は、このカンマ区切りリストを割り当ての左辺で使用する例です。

 
[x.a] = deal ("new string1", "new string2");
 x(1).a
     ⇒ ans = new string1
 x(2).a
     ⇒ ans = new string2

数値配列に限られますが、インデクスにベクターを使用できます(Index Expressionsを参照):

 
x(3:4) = x(1:2);
[x([1,3]).a] = deal ("other string1", "other string2");
x.a
     ⇒
        ans = other string1
        ans = new string2
        ans = other string2
        ans = new string2

関数sizeは構造体のサイズをリターンします。上記の例にたいしては以下のようになります

 
size (x)
     ⇒ ans =

          1   4

構造体配列の要素は、要素に空マトリクスを割り当てることにより、数値配列と同様のやり方で削除できます。たとえば

 
in = struct ("call1", {x, Inf, "last"}, 
             "call2", {x, Inf, "first"})
     ⇒ in =
        {
          1x3 struct array containing the fields:

            call1
            call2
        }

in(1) = [];
in.call1
     ⇒
       ans = Inf
       ans = last

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.1.3 Creating Structures

インデクス演算子"."とは別に、octaveでは動的名前付け"(var)"、またはstructを使用して構造体を作成できます。動的名前付けでは、変数の文字列値をフィールド名に使用します。たとえば:

 
a = "field2";
x.a = 1;
x.(a) = 2;
x
     ⇒ x =
        {
          a =  1
          field2 =  2
        }

動的インデクス付けでは、Octaveで有効な識別子だけでなく、任意の文字列を使用できます(これはMATLABでは機能しないことに注意してください):

 
a = "long field with spaces (and funny char$)";
x.a = 1;
x.(a) = 2;
x
     ⇒ x =
        {
          a =  1
          long field with spaces (and funny char$) =  2
        }

警告IDのOctave:matlab-incompatibleによい、この使用についての警告を有効にできます。warning_idsを参照してください。

実際には、データ構造体の正確なフィールド名を構築するときに、文字列を操作するすべての関数を使用できます。

 
names = ["Bill"; "Mary"; "John"];
ages  = [37; 26; 31];
for i = 1:rows (names)
  database.(names(i,:)) = ages(i);
endfor
database
     ⇒ database =
        {
          Bill =  37
          Mary =  26
          John =  31
        }

構造体を作成する3つ目の方法は、structコマンドです。structは1対の引数をとります。1つ目の引数は構造体内に含めるためのfieldnameで、2つ目はスカラーまたはセル配列です。たとえば:

 
struct ("field1", 1, "field2", 2)
⇒ ans =
      {
        field1 =  1
        field2 =  2
      }

structにスカラーとセル配列が混交された値が渡された場合は、矛盾しない次元の構造体配列を作成するようにスカラー引数が展開されます。たとえば:

 
s = struct ("field1", {1, "one"}, "field2", {2, "two"},
        "field3", 3);
s.field1
     ⇒ 
        ans =  1
        ans = one

s.field2
     ⇒
        ans =  2
        ans = two

s.field3
     ⇒
        ans =  3
        ans =  3

セル配列を特定のフィールドに含む構造体を作成したい場合は、以下の例のようにそれを別のセル配列でラップしなければなりません:

 
struct ("field1", {{1, "one"}}, "field2", 2)
     ⇒ ans =
        {
          field1 =

        {
          [1,1] =  1
          [1,2] = one
        }

          field2 =  2
        }

Built-in Function: s = struct ()
Built-in Function: s = struct (field1, value1, field2, value2, …)
Built-in Function: s = struct (obj)

スカラーまたは配列の構造体を作成して、値を初期化します。変数field1field2、…はフィールド名を指定する文字列で、変数value1value2、…には任意の型を使用できます。

値がセル配列の場合は構造体配列を作成して、値を初期化します。値となる各セル配列の次元は一致していなければなりません。シングルトンのセルおよび非セル値は、配列全体を満たすように繰り返されます。セルが空の場合は、指定されたフィールド名の空の構造体配列が作成されます。

引数がオブジェクトの場合は、それにもとづいた構造体をリターンします。

構文が構造体配列に最適化されていることに注目してください。以下の例で考えてみましょう:

 
struct ("foo", 1)
  ⇒ scalar structure containing the fields:
    foo =  1

struct ("foo", {})
  ⇒ 0x0 struct array containing the fields:
    foo

struct ("foo", { {} })
  ⇒ scalar structure containing the fields:
    foo = {}(0x0)

struct ("foo", {1, 2, 3})
  ⇒ 1x3 struct array containing the fields:
    foo

1つ目は通常のスカラー構造体で、1つのフィールドと1つの値をもちます。2つ目は値をもたない1つのフィールドをもつ、空の構造体配列を作成します。値が1つのエントリーを含むセル配列の場合は、そのフィールドの値が単一のエントリーとなるようなスカラー構造体になります。そのような単一のエントリーは、空のセル配列にたいして発生します。

最後に値が非スカラーのセル配列の場合、structは構造体配列を作成します。

See also: cell2struct, fieldnames, orderfields, getfield, setfield, rmfield, structfun.

オブジェクトが構造体または構造体配列かをテストするのに、関数isstructを使用してできます。

Built-in Function: isstruct (x)

xが構造体または構造体配列の場合は、trueをリターンします。

See also: ismatrix, iscell, isa.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.1.4 Manipulating Structures

以下は、構造体のフィールドを操作する関数です。

Built-in Function: nfields (s)

構造体sのフィールド数をリターンします。

See also: fieldnames.

Function File: names = fieldnames (struct)
Function File: names = fieldnames (obj)
Function File: names = fieldnames (javaobj)
Function File: names = fieldnames ("jclassname")

入力で指定されたフィールド名により、文字列のセル配列をリターンします。

入力が構造体structの場合、構造体の要素が名前になります。

入力がOctaveオブジェクトobjの場合、オブジェクトのパブリックプロパティが名前になります。

入力がJavaオブジェクトjavaobj、またはJavaクラス名jclassnameの場合、オブジェクトまたはクラスのパブリックなデータ要素が名前になります。

See also: nfields, isfield, orderfields, struct, methods.

Built-in Function: isfield (x, "name")
Built-in Function: isfield (x, name)

xが構造体でnameという名前の要素を含む場合は、trueをリターンします。nameが文字列のセル配列の場合は、等しい次元の論理配列をリターンします。

See also: fieldnames.

Function File: s = setfield (s, field, val)
Function File: s = setfield (s, idx1, field1, idx2, field2, …, val)

構造体sのフィールドメンバーfieldを、valにセットします。たとえば:

 
s = struct ();
s = setfield (s, "foo bar", 42);

これは以下と等価です

 
s.("foo bar") = 42;

フィールド名は有効なOctave識別子ではないので、ここでは通常の構造体構文s.foo bar = 42は使用できないことに注意してください。フィールド名に任意の文字列を使用するのはMATLABと互換性がないので、Octave:matlab-incompatible警告がセットされている場合はこの使用にたいして警告されるでしょう。XREFwarning_idsを参照してください。

2つ目の呼び出し形式では、構造体配列のフィールドへのセットはインデクスidx1idx2、…とフィールドfield1, field2, …のように連続してネストされているかもしれません。インデクスは、そのネスト深さでの期待されるインデクスを含むセルでなければなりません。

したがって以下のように考えることができます

 
s = struct ("baz", 42);
setfield (s, {1}, "foo", {1}, "bar", 5)
    ⇒ ans =
    scalar structure containing the fields:
      baz =  42
      foo =
        scalar structure containing the fields:
          bar =  5

ここでは最初に通常の構造体配列のフィールドbazに42をセットしています。それから一意なインデクスを含む単独セル2つによりインデクス付けされる、別のネストされたスカラー構造体フィールドに値をセットしています。

最後は、ネストされた構造体配列の例です

 
sa.foo = 1;
sa = setfield (sa, {2}, "bar", {3}, "baz", 6);
sa(2).bar(3)
     ⇒ ans =
     scalar structure containing the fields:
       baz =  6

ここではsaは構造体配列で、要素1がフィールドfdで、2つ目のフィールドは3つ目の要素が構造体であるような別の構造体配列です

以下のようにして、上記の例と同じ結果を得られることに注意してください:

 
SA.foo = 1;
SA(2).bar(3).baz = 6

See also: getfield, rmfield, isfield, fieldnames, isstruct, struct.

Function File: [val] = getfield (s, field)
Function File: [val] = getfield (s, idx1, field1, idx2, field2, …)

構造体(またはネストされた構造体)からフィールドを抽出します。構文はsetfieldと同様ですが、最後のvalがなく、値をセットするかわりに、値をリターンする点が異なります。

See also: setfield, rmfield, isfield, fieldnames, isstruct, struct.

Built-in Function: s = rmfield (s, "f")
Built-in Function: s = rmfield (s, f)

構造体(または構造体配列)sからフィールドfを削除したコピーをリターンします。fが文字列のセル配列か文字配列の場合は、それぞれの名前付きフィールドを削除します。

See also: orderfields, fieldnames.

Function File: [t, p] = orderfields (s1)
Function File: [t, p] = orderfields (s1, s2)

アルファベット順、またはs2で指定された順にフィールドを整列したs1のコピーをリターンします。

1つの構造体が与えられた場合は、s1のフィールド名をアルファベット順に整列します。

2つ目の引数が構造体の場合は、s1のフィールド名をs2に出現する順に整列します。2つ目の引数には順序を指定する置換ベクター(permutation vector)、または望む順に整列されたs1内のフィールド名を含む文字列のセル配列を指定することもできます。

2つ目のオプション出力引数pには、元の名前順を新しい名前順に変換する置換ベクターが割り当てられます。

例:

 
s = struct ("d", 4, "b", 2, "a", 1, "c", 3);
t1 = orderfields (s)
     ⇒ t1 =
        {
          a =  1
          b =  2
          c =  3
          d =  4
        }
t = struct ("d", {}, "c", {}, "b", {}, "a", {});
t2 = orderfields (s, t)
     ⇒ t2 =
        {
          d =  4
          c =  3
          b =  2
          a =  1
        }
t3 = orderfields (s, [3, 2, 4, 1])
     ⇒ t3 =
        {
          a =  1
          b =  2
          c =  3
          d =  4
        }
[t4, p] = orderfields (s, {"d", "c", "b", "a"})
     ⇒ t4 =
        {
          d =  4
          c =  3
          b =  2
          a =  1
        }
        p =
           1
           4
           2
           3

See also: getfield, rmfield, isfield, isstruct, fieldnames, struct.

Function File: substruct (type, subs, …)

subsrefおよびsubsasgnで使用するための添字構造体(subscript structure)を作成します。たとえば:

 
idx = substruct ("()", {3, ":"})
     ⇒
       idx =
       {
         type = ()
         subs =
         {
           [1,1] =  3
           [1,2] = :
         }
       }
x = [1, 2, 3; 4, 5, 6; 7, 8, 9];
subsref (x, idx)
   ⇒ 7  8  9

See also: subsref, subsasgn.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.1.5 Processing Data in Structures

構造体内のデータを処理するには、forループを使用するのが一番シンプルな方法です(Looping Over Structure Elementsを参照)。構造体の各フィールドにユーザー定義関数を適用するstructfun関数でも、同様の効果を得ることができます。structfunを参照してください。

かわりに、構造体内のデータを処理するために、処理の前に構造体を他のコンテナー型に変換すると良いかもしれません。

Built-in Function: c = struct2cell (s)

構造体オブジェクトに格納されたオブジェクトから、新たなセル配列を作成します。fが構造体内のフィールド数の場合、結果となるセル配列は[f size(s)]に応じた次元のベクターとなります。たとえば:

 
s = struct ("name", {"Peter", "Hannah", "Robert"},
           "age", {23, 16, 3});
c = struct2cell (s)
   ⇒ c = {2x1x3 Cell Array}
c(1,1,:)(:)
   ⇒
      {
        [1,1] = Peter
        [2,1] = Hannah
        [3,1] = Robert
      }
c(2,1,:)(:)
   ⇒
      {
        [1,1] = 23
        [2,1] = 16
        [3,1] = 3
      }

See also: cell2struct, fieldnames.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.2 Cell Arrays

複数の異なるサイズや型の変数を、1つの変数に格納するのが必要だったり便利なことがあるかもしれません。セル配列はまさにそれを行うことを可能にするコンテナークラスです。一般的にセル配列はN次元配列と同様に機能しますが、割り当てとインデクスの演算子に‘{’と‘}’を使用する点が異なります。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.2.1 Basic Usage of Cell Arrays

以下は文字列と2行2列の乱数行列を含むセル配列を作成するコードの例です

 
c = {"a string", rand(2, 2)};

セル配列の要素にアクセスするために、{および}演算子でインデクス付けすることができます。したがって上記の例で作成された変数は、以下のようにインデクス付けできます:

 
c{1}
     ⇒ ans = a string

数値配列と同様に、セル配列の複数の要素をインデクス用ベクターでインデクス付けして抽出できます。

 
c{1:2}
     ⇒ ans = a string
     ⇒ ans =

               0.593993   0.627732
               0.377037   0.033643

インデクス演算子はセル配列に要素を挿入したり上書きするためにも使用できます。以下のコードでは、上記で作成したセル配列の3番目にスカラーの3を挿入しています

 
c{3} = 3
     ⇒ c =

         {
           [1,1] = a string
           [1,2] =

              0.593993   0.627732
              0.377037   0.033643

           [1,3] =  3
         }

セル配列のインデクス操作についての詳細はIndexing Cell Arraysを参照してください。

前の例のように、一般的にネストされたセル配列は階層的に表示されます。それらをインデクスにより参照するほうが理解しやすい場合は、celldisp関数を使用できます。

Function File: celldisp (c)
Function File: celldisp (c, name)

セル配列の内容を再帰的に表示します。デフォルトでは、値は変数cの名前とともに表示されます。しかし、この名前は変数nameで置き換えることができます。たとえば:

 
c = {1, 2, {31, 32}};
celldisp (c, "b")
   ⇒
      b{1} =
       1
      b{2} =
       2
      b{3}{1} =
       31
      b{3}{2} =
       32

See also: disp.

オブジェクトがセル配列かどうかテストするには、iscell関数を使用します。たとえば:

 
iscell (c)
     ⇒ ans = 1

iscell (3)
     ⇒ ans = 0

Built-in Function: iscell (x)

xがセル配列の場合は、trueをリターンします。

See also: ismatrix, isstruct, iscellstr, isa.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.2.2 Creating Cell Arrays

冒頭に紹介した例(Basic Usage of Cell Arraysを参照)では、現在利用可能な変数を含むセル配列を作成する方法を示しました。しかし、セル配列を作成した後にデータをセットするほうが便利な場合も多いでしょう。

cell関数は与えられたサイズの空マトリクスを含むセル配列をリターンします。この関数は、新たに数値配列を作成するzeros関数に似ています。以下は空マトリクスを含む2行2列のセル配列を作成する例です

 
c = cell (2,2)
     ⇒ c =

         {
           [1,1] = [](0x0)
           [2,1] = [](0x0)
           [1,2] = [](0x0)
           [2,2] = [](0x0)
         }

数値配列と同様に、セル配列を多次元にすることもできます。cell関数hqリターンされるセル配列のサイズを決定するために、任意の個数の正の整数を受け入れます。正の整数のベクターによりセル配列のサイズをセットすることもできます。以下の例では、サイズの等しい2つのセル配列を作成して、1つ目のセル配列にサイズを表示しています

 
c1 = cell (3, 4, 5);
c2 = cell ( [3, 4, 5] );
size (c1)
     ⇒ ans =
         3   4   5

これまで見てきたように、size関数はセル配列にたいしても機能します。lengthnumelrowscolumnsのようなサイズを報告する他の関数も同様に機能します。

Built-in Function: cell (n)
Built-in Function: cell (m, n)
Built-in Function: cell (m, n, k, …)
Built-in Function: cell ([m n …])

新たにセル配列オブジェクトを作成します。

1つのスカラー整数引数とともに呼び出された場合は、NxNの正方セル配列をリターンします。2つ以上のスカラー整数引数、または整数値ベクターとともに呼び出された場合は、与えられた次元の配列をリターンします。

See also: cellstr, mat2cell, num2cell, struct2cell.

空のセル配列を作成してから値をセットする別の方法としてnum2cellmat2cellcellslices関数を使用して数値配列をセル配列に変換する方法が利用できます。

Built-in Function: C = num2cell (A)
Built-in Function: C = num2cell (A, dim)

数値マトリクスAをセル配列に変換します。dimが定義されている場合は、Cがこの次元での次元1となり、Aの要素はCにスライスとして配されます。たとえば:

 
num2cell ([1,2;3,4])
   ⇒
      {
        [1,1] =  1
        [2,1] =  3
        [1,2] =  2
        [2,2] =  4
      }
num2cell ([1,2;3,4],1)
   ⇒
      {
        [1,1] =
           1
           3
        [1,2] =
           2
           4
      }

See also: mat2cell.

Built-in Function: C = mat2cell (A, m, n)
Built-in Function: C = mat2cell (A, d1, d2, …)
Built-in Function: C = mat2cell (A, r)

マトリクスAをセル配列に変換します。Aが2次元の場合、sum (m) == size (A, 1)sum (n) == size (A, 2)が成り立つ必要があります。同様にAが多次元で次元数の引数がAの次元と等しい場合は、sum (di) == size (A, i)が成り立つ必要があります。

単一の次元引数rが与えられた場合、他の次元引数はsize (A,i)と等しいとみなされます。

以下はmat2cellを使用する例です

 
mat2cell (reshape (1:16,4,4), [3,1], [3,1])
⇒
{
   [1,1] =

      1   5   9
      2   6  10
      3   7  11

   [2,1] =

      4   8  12

   [1,2] =

     13
     14
     15

   [2,2] = 16
}

See also: num2cell, cell2mat.

Built-in Function: sl = cellslices (x, lb, ub, dim)

与えられた配列xにたいして、この関数はインデクスベクターlbおよびub(下限と上限を指定)から決定される配列スライスのセル配列を生成します。言い換えると、これは以下のコードと等価です:

 
n = length (lb);
sl = cell (1, n);
for i = 1:length (lb)
  sl{i} = x(:,…,lb(i):ub(i),…,:);
endfor

インデクスの位置はdimにより決定されます。指定されなかった場合は、最初の非シングルトン次元に沿ってスライシングが行われます。

See also: cell2mat, cellindexmat, cellfun.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.2.3 Indexing Cell Arrays

Basic Usage of Cell Arraysで見た‘{’および‘}’演算子を使用して、セル配列の要素を抽出できます。セル配列のままで部分配列を抽出、またはアクセスしたい場合は‘(’および‘)’演算子を使う必要があります。この違いを以下の例で示します:

 
c = {"1", "2", "3"; "x", "y", "z"; "4", "5", "6"};
c{2,3}
     ⇒ ans = z

c(2,3)
     ⇒ ans = 
        {
          [1,1] = z
        }

So with ‘{}’ you access elements of a cell つまり‘{}’ではセル配列の要素にアクセスしますが、‘()’ではセル配列の部分配列にアクセスすることになります。

(’および‘)’演算子を使用することにより、多次元配列と同様にセル配列のインデクス操作を行うことができます。たとえば、以下のコマンドでセル配列のすべての行の1列目と3列目に0をセットできます。

 
c(:, [1, 3]) = {0}
     ⇒  =
        {
          [1,1] = 0
          [2,1] = 0
          [3,1] = 0
          [1,2] = 2
          [2,2] =  10
          [3,2] =  20
          [1,3] = 0
          [2,3] = 0
          [3,3] = 0
        }

以下のようにも記述できることに注意してください:

 
c(:, [1, 3]) = 0;

Here, the scalar ‘0’ is automatically promoted to ここではスカラー‘0’が自動的にセル配列‘{0}’に昇格されて、cの部分配列に割り当てられています。

()’によるセル配列のインデクス操作として、以下のコマンドはセル配列の1行目と2行目を交換する例です:

 
c = {1, 2, 3; 4, 5, 6};
c([1, 2], :) = c([2, 1], :)
     ⇒ = 
        {
          [1,1] =  4
          [2,1] =  1
          [1,2] =  5
          [2,2] =  2
          [1,3] =  6
          [2,3] =  3
        }

{’および‘}’演算子によりセル配列の複数要素にアクセスすると、結果は要求されたすべての要素のカンマ区切りリストになります(Comma Separated Listsを参照)。‘{’および‘}’演算子を使用することにより、上記の例の最初の2行は以下のように書き換えることができます:

 
[c{[1,2], :}] = deal (c{[2, 1], :})
     ⇒ = 
        {
          [1,1] =  1
          [2,1] =  4
          [1,2] =  2
          [2,2] =  5
          [1,3] =  3
          [2,3] =  6
        }

構造体配列や数値配列のように、セル配列から要素を削除するために空マトリクス‘[]’を使用できます:

 
x = {"1", "2"; "3", "4"};
x(1, :) = []
     ⇒ x =
        {
          [1,1] = 3
          [1,2] = 4
        }

以下はセル配列から要素の内容だけを削除する方法を示す例です:

 
x = {"1", "2"; "3", "4"};
x{1, :} = []
⇒ x =
      {
        [1,1] = [](0x0)
        [2,1] = 3
        [1,2] = [](0x0)
        [2,2] = 4
      }

インデクス操作はセル配列内のオブジェクトではなく、セル配列を操作します。対照的に、cellindexmatは各セル配列エントリー内のオブジェクトにたいするマトリクスのインデクス操作に適用され、要求された値をリターンします。

Built-in Function: y = cellindexmat (x, varargin)

与えられたマトリクスxのセル配列にたいして、この関数は以下の計算を行います

 
Y = cell (size (X));
for i = 1:numel (X)
  Y{i} = X{i}(varargin{:});
endfor

See also: cellslices, cellfun.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.2.4 Cell Arrays of Strings

一般的に、セル配列は複数の文字列を1つの変数に格納するために使用されます。各行を文字列とみなせば、文字マトリクスに複数文字列を格納することもできます。しかしこれは、すべての文字列が同じ長さにしなければならないという問題が生じます。したがって、複数文字列の格納にはセル配列の使用を推奨します。ある操作に文字マトリクス表現が要求されるような場合に備えて、文字列のセル配列を文字マトリクスに変換したり、その逆を行う関数がいくつかあります。cellstrは文字配列を文字列のセル配列に変換しますが、charstrvcatはセル配列を文字配列に変換します(Concatenating Stringsを参照)。

 
a = ["hello"; "world"];
c = cellstr (a)
     ⇒ c =
         {
           [1,1] = hello
           [2,1] = world
         }

Built-in Function: cstr = cellstr (strmat)

文字列配列strmatの要素から、新たにセル配列オブジェクトを作成します。

strmatの各行が、cstrの要素になります。行内の末尾のスペースは、変換の前に削除されます。

文字列のセル配列から文字配列に逆変換するにはcharを使用します。

See also: cell, char.

複数の文字列を格納するのにセル配列を使用する他の利点として、Octaveに同梱されている文字列を操作する関数の多くがこの表現をサポートする点が挙げられます。例として、strcmp関数を使用することにより、1つの文字列を、他の多くのものと比較できます。この関数の引数の1つが文字列で、それ以外は文字列のセル配列の場合、セル配列の各要素が文字列と比較されます:

 
c = {"hello", "world"};
strcmp ("hello", c)
     ⇒ ans =
        1   0

次の文字列関数が文字列のセル配列をサポートします: charstrvcatstrcat (Concatenating Stringsを参照)、strcmpstrncmpstrcmpistrncmpi (Comparing Stringsを参照)、str2doubledeblankstrtrimstrtruncstrfindstrmatchregexpregexpi (Manipulating Stringsを参照)、str2double (String Conversionsを参照)。

関数iscellstrは、オブジェクトが文字列のセル配列かテストするのに使用できます。

Built-in Function: iscellstr (cell)

セル配列cellのすべての要素が文字列の場合は、trueをリターンします。

See also: ischar.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.2.5 Processing Data in Cell Arrays

セル配列に格納されたデータは、実際のデータに応じて複数の方法により処理されます。forループを使用して処理を繰り返すのが、そのデータを処理するもっともシンプルな方法です。セル配列のすべての要素にユーザー定義関数を呼び出すcellfun関数の使用を通じて、さらに簡単に同じアイデアを実装できます。cellfunを参照してください。

かわりにマトリクスやデータ構造体のような、異なるコンテナーにデータを変換することもできます。データに応じてcell2mat、およびcell2struct関数の利用が可能です。

Function File: m = cell2mat (c)

セル配列cのすべての要素を連結することによりマトリクスにして超矩形(hyperrectangle)に変換します。cの要素は数値、論理値、文字マトリクス、セル配列、構造体でなければならず、catはそれらを連結できなければなりません。

See also: mat2cell, num2cell.

Built-in Function: cell2struct (cell, fields)
Built-in Function: cell2struct (cell, fields, dim)

cellを構造体に変換します。fields内のフィールド数は、次元dimにしたがったcellの要素数に一致(numel (fields) == size (cell, dim))しなければなりません。dimが省略された場合、値は1とみなされます。

 
A = cell2struct ({"Peter", "Hannah", "Robert";
                   185, 170, 168},
                 {"Name","Height"}, 1);
A(1)
   ⇒
      {
        Name   = Peter
        Height = 185
      }

See also: struct2cell, cell2mat, struct.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.3 Comma Separated Lists

カンマ区切りリスト(2)はすべてのOctave関数の基本的な引数型(入力引数とリターン引数の両方)です。

 
max (a, b)

上記の例では‘a, b’がカンマ区切りリストです。カンマ区切りリストは代入の右辺と左辺の両方に出現することができます。たとえば

 
x = [1 0 1 0 0 1 1; 0 0 0 0 0 0 7];
[i, j] = find (x, 2, "last");

ここでは‘x, 2, "last"’はfindの入力引数を構成するカンマ区切りリストです。findはカンマ区切りリストの出力引数をリターンし、それらは要素ごとにカンマ区切りリスト‘i, j’に割り当てられます。

カンマ区切りリストが使用される他の例としては、[]による新たな配列の作成(Matricesを参照)や、{}によるセル配列の作成(Basic Usage of Cell Arraysを参照)があります。

 
a = [1, 2, 3, 4];
c = {4, 5, 6, 7};

この場合は‘1, 2, 3, 4’と‘4, 5, 6, 7’の両方がカンマ区切りリストです。

カンマ区切りリストはユーザーが直接扱うことはできません。しかし構造体配列とセル配列はどちらもカンマ区切りリストに変換できるので、明示的にカンマ区切りリストを記述するかわりに使用することができます。この機能は、以降のサブセクションで示すように、有用な場面が多数あります。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.3.1 Comma Separated Lists Generated from Cell Arrays

これまで示したように(Indexing Cell Arraysを参照)、セル配列は{および}演算子でカンマ区切りリストに抽出できます。このリストを[]で囲うことにより、配列に連結できます。たとえば:

 
a = {1, [2, 3], 4, 5, 6};
b = [a{1:4}]
     ⇒ b =
         1   2   3   4   5

同様に{}で選択されたセル要素を含む、新たなセル配列を作成することができます。以下の例で示すように、リストを‘{’と‘}’で囲えば、新しいセル配列が作成されます:

 
a = {1, rand(2, 2), "three"};
b = { a{ [1, 3] } }
     ⇒ b =
         {
           [1,1] =  1
           [1,2] = three
         }

さらに({}によりアクセスされる)セル要素を、直接関数に渡すことができます。セル配列の要素リストは、あたかもその要素を引数として呼び出したかのように、関数の引数として渡すことができます。以下の例の2つのprintf呼び出しは等価ですが、後者はよりシンプルで、任意のサイズのセル配列を処理できます:

 
c = {"GNU", "Octave", "is", "Free", "Software"};
printf ("%s ", c{1}, c{2}, c{3}, c{4}, c{5});
     -| GNU Octave is Free Software 
printf ("%s ", c{:});
     -| GNU Octave is Free Software 

代入の左辺で使用する場合、{}で生成されたカンマ区切りリストに代入できます。以下は例です

 
in{1} = [10, 20, 30, 40, 50, 60, 70, 80, 90];
in{2} = inf;
in{3} = "last";
in{4} = "first";
out = cell (4, 1);
[out{1:3}] = find (in{1 : 3});
[out{4:6}] = find (in{[1, 2, 4]})
     ⇒ out =
        {
          [1,1] = 1
          [2,1] = 9
          [3,1] = 90
          [4,1] = 1
          [3,1] = 1
          [4,1] = 10
        }

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6.3.2 Comma Separated Lists Generated from Structure Arrays

同様に構造体配列もカンマ区切りリストの生成に使用できます。これは構造体配列の1つのフィールドをアドレッシングすることにより行われます。たとえば:

 
x = ceil (randn (10, 1)); 
in = struct ("call1", {x, 3, "last"}, 
             "call2", {x, inf, "first"});
out = struct ("call1", cell (2, 1), "call2", cell (2, 1));
[out.call1] = find (in.call1);
[out.call2] = find (in.call2);

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7. Variables

変数により、値に名前を付け、後でそれを参照できるようになります。これまで多くの例で、すでに変数を目にしてきました。変数の名前は英数字とアンダースコアのシーケンスですが、数字で開始することはできません。Octaveは変数の名前の長さに制限は強いませんが、30文字を超える長さの変数名が有用なことはまれです。以下はすべて有効な変数名です

 
x
x15
__foo_bar_baz__
fucnrdthsucngtagdjb

しかし、__foo_bar_baz__のように開始と終了が2つのアンダースコアの名前は、Octaveが内部で使用するために予約されています。これらの名前のは、ドキュメントされたOctaveの内部変数やビルトインシンボル定数を除き、あなたが記述するコードで使用するべきではありません。

変数名は大文字小文字を区別します。シンボルaAは別の変数です。

変数名は、それ自体が有効な式です。変数名は、その変数の現在の値を表します。変数は代入演算子加算演算子により新たな値が与えられます。Assignment Expressionsを参照してください。

特別な意味をもつビルトイン変数が1つあります。ans変数は、出力がどの変数にも割り当てられていないとき、常に最後の計算結果を保持します。コードa = cos (pi)は変数aに-1を代入しますが、ansの値は変更しません。しかしコードcos (pi)ansの値を-1にセットします。

Octaveの変数は固定された型をもたないので、変数に最初は数値を格納して、同じプログラム内で後で文字列を保持するために同じ名前を使用できます。値を与える前に変数を使用するべきではありません。これを行うと結果はエラーになります。

Automatic Variable: ans

明示的に変数に代入されていない、もっとも最近の計算結果です。たとえば、

 
3^2 + 4^2

この式が評価された後にansがリターンする値は25です。

Built-in Function: isvarname (name)

nameが有効な変数名の場合は、trueをリターンします。

See also: iskeyword, exist, who.

Function File: varname = genvarname (str)
Function File: varname = genvarname (str, exclusions)

strから一意な変数を作成します。exclusionsが与えられた場合、それぞれの変数およびexclusionsにたいして一意になります(exclusionsには文字列とセル文字列を指定できます)。

strがセル文字列の場合は、str内の各セルにたいして一意な変数が作成されます。

 
x = 3.141;
genvarname ("x", who ())
  ⇒ x1

strがセル配列の場合、genvarnameは文字列を確実に分離するようにします:

 
genvarname ({"foo", "foo"})
  ⇒
     {
       [1,1] = foo
       [1,2] = foo1
     }

結果は変数自体ではなく、文字配列または文字列のセル配列になることに注意してください。変数の定義には、eval()を使用できます。以下はx42をセットする例です。

 
name = genvarname ("x");
eval ([name " = 42"]);
  ⇒ x =  42

これは一意な構造体フィールド名の作成にも便利です。

 
x = struct ();
for i = 1:3
  x.(genvarname ("a", fieldnames (x))) = i;
endfor
  ⇒ x =
     {
       a =  1
       a1 =  2
       a2 =  3
     }

変数名に含むことができるのは英数字とアンダースコアだけなので、genvarnameは許可されていない文字シーケンスをアンダースコアで置き換えます。さらに変数名は数字で開始できないので、このような場合は変数名の最初にアンダースコアを追加します。

開始と終了が2つのアンダースコア"__"であるような変数名は有効ですが、そのような名前はoctaveにより内部的に使用されるので一般的には避けるべきで、genvarnameはそのような名前を生成しません。

またgenvarnameは"for""if"のようなキーワードと衝突しない名前をリターンします。必要なら数字が追加されます。しかし、これには"sin"のような函数名は含まれないことに注意してください。必要なら、そのような名前はexclusionsに含めるべきです。

See also: isvarname, exist, tmpnam, eval.

Function File: namelengthmax ()

MATLABと互換性のある変数名の最大長をリターンします。Octaveは長さ2^31 - 1までの文字列を格納できます。しかしMATLABとの互換性のためすべての変数、関数、構造体フィールド名はnamelengthmaxで得られる長さより短くする必要があります。特にMATLABファイルフォーマットに格納する変数は、この長さに切り詰められます。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.1 Global Variables

globalと宣言された変数は、それが形式にしたがって渡されたパラメーターでなくても、関数ボディーの内部からアクセスできます。

global宣言文を使用して変数をグローバルに宣言できます。以下の命令文はすべてグローバル宣言です。

 
global a
global a b
global c = 2
global d = 3 e f = 5

グローバル変数はglobal文で1度だけ初期化されます。たとえば、

 
global gvar = 1
global gvar = 2

この文が実行されるとグローバル変数gvarの値は2ではなく1になります。‘clear gvar’コマンドを実行しても上記の振る舞いは変更されません。‘clear all’により変更されます。

グローバル変数にアクセスするために、関数内で変数をグローバルと宣言することが必要です。たとえば、

 
global x
function f ()
  x = 1;
endfunction
f ()

これはグローバル変数xの値を1にセットしません。グローバル変数xの値を変更するには、以下のように関数ボディー内でそれをグローバルとセットしなければなりません

 
function f ()
  global x;
  x = 1;
endfunction

関数のパラメーターリストにグローバル変数を渡しても、それはローカルコピーを作成し、グローバルな値は変更されないでしょう。たとえば関数が以下で与えられ

 
function f (x)
  x = 0
endfunction

トップレベルでxをグローバル変数とする定義が以下の場合

 
global x = 13

以下の式

 
f (x)

は関数内部のxの値として0を表示し、トップレベルのxの値は変更されないまま残ります。なぜなら関数は引数のコピーにたいして機能するからです。

Built-in Function: isglobal (name)

nameがグローバルに可視な変数の場合は、trueをリターンします。たとえば:

 
global x
isglobal ("x")
   ⇒ 1

See also: isvarname, exist.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.2 Persistent Variables

関数内で永続的(persistent)と宣言された変数は、同じ関数にたいする一連の呼び出しの間、その内容をメモリー内にとどめます。永続的変数ちとグローバル変数に違いは、永続的変数のスコープが特定の関数にたいしてローカルであり、それ以外の場所からは不可視であることです。

以下は、永続的変数を使用して、呼び出された回数をプリントする関数を作成する例です。

 
function count_calls ()
  persistent calls = 0;
  printf ("'count_calls' has been called %d times\n",
          ++calls);
endfunction

for i = 1:3
  count_calls ();
endfor

-| 'count_calls' has been called 1 times
-| 'count_calls' has been called 2 times
-| 'count_calls' has been called 3 times

例示すように変数persistent宣言文により永続的であると宣言されます。以下の命令文はすべて永続的な宣言です。

 
persistent a
persistent a b
persistent c = 2
persistent d = 3 e f = 5

永続的変数の振る舞いは、Cの静的変数と同じです。Octaveではコマンドstaticも認識され、これはpersistentと等価です。

グローバル変数と同様、永続的変数は1度だけ初期化されます。たとえば、

 
persistent pvar = 1
persistent pvar = 2

この式を実行すると、永続的変数pvarの値じゃ2ではなく1になります。

永続的変数が宣言されていても特定の値に初期化されていない場合、値は空マトリクスになります。したがって以下の例で示すように、空かどうかチェックすることにより永続的変数を初期化することも可能です。

 
function count_calls ()
  persistent calls;
  if (isempty (calls))
    calls = 0;
  endif
  printf ("'count_calls' has been called %d times\n",
          ++calls);
endfunction

この実装は、count_callsの以前の実装と正確に同じ方法で振る舞います。

永続的変数の値は、明示的にクリアーされるまでメモリー内にとどまります。count_callsの実装がディスク上に保存されていると仮定すると、以下のような振る舞いになります。

 
for i = 1:2
  count_calls ();
endfor
-| 'count_calls' has been called 1 times
-| 'count_calls' has been called 2 times

clear
for i = 1:2
  count_calls ();
endfor
-| 'count_calls' has been called 3 times
-| 'count_calls' has been called 4 times

clear all
for i = 1:2
  count_calls ();
endfor
-| 'count_calls' has been called 1 times
-| 'count_calls' has been called 2 times

clear count_calls
for i = 1:2
  count_calls ();
endfor
-| 'count_calls' has been called 1 times
-| 'count_calls' has been called 2 times

つまり、変数を含む関数がメモリーから削除されるときだけ、永続的変数が削除されます。Octaveから関数定義を直接タイプした場合は、メモリーから関数定義全体を削除するclearコマンドにより、永続的変数が削除されます。関数がクリアーされてもメモリーから永続的変数を削除したくない場合は、mlock関数を使用するべきです(Function Lockingを参照)。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7.3 Status of Variables

シンプルな使い捨てプログラムを作成する場合、プロンプト上でどの変数が利用できるととても便利なことがあります。関数who、および同類のwhoswhos_line_formatは以下で示すように、メモリー内に何があるかについて異なる情報を表示します。

 
str = "A random string";
who -variables
     -| *** local user variables:
     -| 
     -| __nargin__  str

Command: who
Command: who pattern …
Command: who option pattern …
Command: C = who ("pattern", …)

与えられたパターンにマッチする現在定義されている変数をリストします。有効なパターン構文は、clearコマンドで説明されているものと同じです。パターンが与えられない場合は、すべての変数がリストされます。デフォルトでは、ローカルスコープで可視な変数だけが表示されます。

以下は有効なオプションですが、組み合わせることはできません。

global

カレントスコープではなく、グローバルスコープの変数をリストします。

-regexp

パターンは表示する変数をマッチングするときの正規表現です。regexp関数を使用するときと同じパターン構文を指定できます。

-file

次の引数をファイル名として扱います。指定されたファイルで見つかったすべての変数がリストされます。ファイルから変数を読み込むとき、パターンは指定できません。

関数として呼び出された場合は、与えられたパターンにマッチする定義された変数名のセル配列をリターンします。

See also: whos, isglobal, isvarname, exist, regexp.

Command: whos
Command: whos pattern …
Command: whos option pattern …
Command: S = whos ("pattern", …)

与えられたパターンにマッチする、現在定義された変数の詳細な情報を提供します。オプションとパターン構文は、whoコマンドと同じです。各変数についての拡張された情報は、以下のデフォルトエントリーとともにテーブルに要約されます。

Attr

リストされた変数の属性。

blank

ローカルスコープの変数

a

自動変数。自動変数とは、インタープリターにより作成されたもの。例: argn

c

複素数型の変数

f

通常形式のパラメーター(関数の引数)。

g

グローバルスコープの変数。

p

永続的変数。

Name

変数の名前。

Size

変数の論理的サイズ。スカラーは1x1、ベクターは1xNまたはNx1、2次元マトリクスはMxN。

Bytes

変数を格納するために現在使用されているメモリーの量。

Class

変数のクラス。たとえばdouble、single、char、uint16、cell、struct。

関数whos_line_formatを通じて表示される情報の加減をカスタマイズできます。

関数としてwhosが呼び出された場合は、与えられたパターンにマッチする定義された変数名の構造体配列をリターンします。構造体の各フィールドはname、size、bytes、class、global、sparse、complex、nesting、persistentを表します。

See also: who, whos_line_format.

Built-in Function: val = whos_line_format ()
Built-in Function: old_val = whos_line_format (new_val)
Built-in Function: whos_line_format (new_val, "local")

コマンドwhosで使用されるフォーマット文字列にたいして、問い合わせまたはセットを行います。

以下は完全なフォーマット文字列です:

 
%[modifier]<command>[:width[:left-min[:balance]]];

以下のコマンドシーケンスが利用できます:

%a

変数の属性をプリントする(g=global、p=persistent、f=formal parameter、a=automatic variable)。

%b

変数が占めるバイト数をプリントする。

%c

変数のクラス名をプリントする。

%e

変数が保持する要素をプリントする。

%n

変数名をプリントする。

%s

変数の次元をプリントする。

%t

変数の型名をプリントする。

各コマンドはアラインメント修飾子ももつ:

l

左揃え。

r

右揃え(デフォルト)。

c

列揃え(コマンド%sでのみ指定可)。

widthはプリントに使用される最小列値を指定する正の整数です。フィールドは必要に応じて自動的に拡張されるので、最大値は必要ありません。

パラメーターleft-minおよびbalanceは、コマンド‘%s’とともに列アラインメント修飾子が使用されたときだけ利用可能です。balanceはエントリー間を整列するフィールド幅を列数で指定します。ナンバリングは最左列を意味する0から開始されます。left-minは指定されたバランス列の左側の最小フィールド幅を指定します。

デフォルトフォーマットは" %a:4; %ln:6; %cs:16:6:1; %rb:12; %lc:-1;n"です。

関数内から"local"オプションとともに呼び出された場合、変数の変更はその関数および関数のサブルーチンにたいしてローカルになります。関数をexitするとき、変数の元の値がリストアされます。

See also: whos.

どの変数がメモリー内にあるか表示するかわりに、与えられた変数が利用可能か判定することができます。この方法は、変数の存在によりプログラムの挙動を変えることにより可能になります。以下はこれを示す例です。

 
if (! exist ("meaning", "var"))
  disp ("The program has no 'meaning'");
endif

Built-in Function: exist (name, type)

nameが変数として存在する場合は1、絶対ファイル名、またはOctaveのpath上の通常ファイルか(‘.m’を追加することにより)関数ファイルの場合は2、Octaveのpath上の‘.oct’または‘.mex’ファイルの場合は3、ビルトイン関数の場合は5、ディレクトリの場合は7、ファイルに関連付けされていない(コマンドラインで入力された)関数の場合は103をリターンします。

それ以外は0をリターンします。

この関数はOctaveの検索パスにあるnameという名前の通常ファイルの場合は、2をリターンします。他のファイル型についての情報が欲しい場合は、かわりに関数file_in_pathおよびstatを組み合わせて使用するべきです。

オプション引数typeが与えられた場合は、シンボルで指定された型だけをチェックします。有効な型は

"var"

変数だけをチェック。

"builtin"

ビルトイン関数だけをチェック。

"file"

ファイルとディレクトリだけをチェック。

"dir"

ディレクトリだけをチェック。

See also: file_in_loadpath, file_in_path, find_dir_in_path, stat.

通常Octaveはメモリーを管理しますが、メモリーから手動で変数を削除するのが実用的な場合もあるでしょう。これは通常、メモリーの相当量を占める大きな変数を扱うとき必要になります。IEEE浮動小数点フォーマットを使用するコンピューターでは、以下のプログラムは約128MBのメモリーを要求するマトリクスを割り当てます。

 
large_matrix = zeros (4000, 4000);

この変数をメモリー上に保持することは、他の計算の速度低下を招くかもしれないので、メモリーから手動で削除する必要があります。clear関数により、これを行うことができます。

Command: clear [options] pattern …

シンボルテーブルから、与えられたパターンにマッチする名前を削除します。パターンは、以下の特殊文字を含むことができます:

?

任意の1文字にマッチ。

*

0文字以上にマッチ。

[ list ]

listで指定された文字リストにマッチ。1文字目が!^の場合はlistで指定された文字以外のすべての文字にマッチ。たとえば、‘[a-zA-Z]’はすべてのアルファベットの小文字と大文字にマッチ。

たとえば、

 
clear foo b*r

は名前fooと、bで始まりrで終わるすべての名前をクリアーします。

引数を指定せずにclearが呼び出された場合、シンボルテーブルからすべてのユーザー定義変数(ローカルおよびグローバル)がクリアーされます。少なくとも1つの引数とともにclearが呼び出された場合は、引数にマッチする可視の名前だけがクリアーされます。たとえば、関数fooを定義して、その後に代入foo = 2を行ってそれを隠したとします。コマンドclear fooを1度実行することにより、変数定義がクリアーされ、関数としてのfooの定義がリストアされます。clear fooの2度目の実行により、関数定義がクリアーされます。

短い形式と長い形式の両方で、以下のオプションが利用できます

-all, -a

シンボルテーブルから、ローカルおよびグローバルのユーザー定義変数とすべての関数をクリアーする。

-exclusive, -x

後のパターンにマッチしない変数をクリアーする。

-functions, -f

関数とビルトインシンボル名をクリアーする。

-global, -g

グローバルシンボル名をクリアーする。

-variables, -v

ローカル変数名をクリアーする。

-classes, -c

クラス構造体テーブルちすべてのオブジェクトをクリアーする。

-regexp, -r

引数は正規表現と解釈され、それにマッチする変数をクリアーする。

exclusiveの例外として、ダッシュなしのロングオプションも同様に使用できる。

Function File: pack ()

MATLABではワークスペースのメモリーを統合します。この関数は互換性のために提供されており、Octaveでは何も行いません。

関数や変数について、それがファイルシステム上どの位置にあるかなどの情報も、Octaveにより収集できます。これは通常プログラム開発の間のみ有用で、プログラムにとって有用ではありません。

Command: type name
Command: type -q name
Function File: text = type ("name", …)

nameの内容を表示します。nameにはファイル、関数(m-file)、変数、演算子、キーワードを指定できます。

typeは通常、functionやvariableのようにnameのカテゴリーを記述するヘッダー行を前置します。‘-q’オプションにより、この動作を抑制できます。

出力変数が指定されていない場合、内容はスクリーンに表示されます。それ以外は文字列のセル配列がリターンされます。この場合、各要素が要求されあ関数の内容に対応します。

Command: which name …

nameのそれぞれの型を表示します。nameが関数ファイルで定義される場合は、ファイルの関数名も表示されます。

See also: help, lookfor.

Command: what
Command: what dir
Function File: w = what (dir)

ディレクトリdir内のOctave固有のファイルをリストします。dirが指定されない場合は、カレントディレクトリが使用されます。リターン引数が要求された場合、構造体w内に見つかったファイルがリターンされます。

See also: which.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8. Expressions

式はOctaveにおける命令文の基本的な構築ブロックです。式は値に評価され、その値をプリント、テスト、変数に格納、関数に渡すことができ、代入演算子で変数に新たな値を割り当てることもできます。

式は自身の命令文の役割りも果たすことができます他の種の命令文の多くは、処理を行うデータを指定する、1つ以上の式を含みます。他言語と比較して、Octaveの式は変数、配列参照、定数、関数呼び出しを含み、同様にさまざまな種類の演算子によるそれらの組み合わせも含みます。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.1 Index Expressions

インデクス式(index expression)により、マトリクスysベクターの選択した要素の参照と抽出が可能になります。

インデクスはスカラー、ベクター、レンジ、または行や列全体の選択に使用する特殊演算子‘:’です。

ベクターは1つにインデクス式を使用してインデクス付けされます。マトリクス(2次元)およびより高次の多次元配列は、1つのインデクスまたはN個(Nは配列の次元)のインデクスによりインデクス付けされます。2次元またはより高次のデータを1つのインデクス式でインデクス付けする場合、配列の要素は(Fortranのように)列優先で取得されます。

インデクス操作による出力はインデクス式の次元とみなされます。たとえば:

 
a(2)       # 結果はスカラー
a(1:2)     # 結果はベクター
a([1; 2])  # 結果は列ベクター

特殊なケースとして、コロンが1つのインデクスとして使用された場合、出力はベクターまたはマトリクスのすべての要素を含む列ベクターになります。たとえば:

 
a(:)       # 結果は列ベクター
a(:)'      # 結果は行ベクター

上記2つのコード用法は、reshapeなどで任意サイズの配列ではなくシンプルなベクターが必要なとき用いられます。

以下のマトリクスが与えられたとき

 
a = [1, 2; 3, 4]

以下の式はすべて等価で、いずれもマトリクスの最初の行を選択します。

 
a(1, [1, 2])  # 行 1, 列 1、2
a(1, 1:2)     # 行 1, 列のレンジ 1-2
a(1, :)       # 行 1, 列全体

インデクス式において、キーワードendは特定の次元の最後のエントリーを自動的に参照します。このマジックインデクスはレンジで使用することもでき、インデクス操作前に配列範囲を得るためのsizelengthの呼び出しの必要性をなくします。たとえば:

 
a = [1, 2, 3, 4];

a(1:end/2)        # aの最初の半分 => [1, 2]
a(end + 1) = 5;   # 要素の追加
a(end) = [];      # 要素の削除
a(1:2:end)        # aの奇数要素 => [1, 3]
a(2:2:end)        # aの偶数要素 => [2, 4]
a(end:-1:1)       # aの逆 => [4, 3, 2 , 1]

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.1.1 Advanced Indexing

n’次元の配列を‘m’次元のインデクスでインデクス付けできます。より一般的には結果を決定するインデクスセットはインデクスベクター(またはレンジ、スカラー)は直積(Cartesian product: カルテシアン積、デカルト積)により形成されます。

通常、そしてもっとも一般的なケースはm == nで、各インデクスはそれぞれの次元に対応します。m < nで各インデクスがi番目の次元において配列サイズより小さい場合、インデクス式は末尾のシングルトン次元([ones (m-n, 1)])とともに渡されます。m < nだがインデクスの1つm(i)が現在の配列のサイズの外側の場合、最後のn-m+1次元が元の次元を掛け合わせた結果と等しくなるように拡張されてシングルトン次元に折り畳まれます。例で理解するのがもっとも簡単でしょう。

 
a = reshape (1:8, 2, 2, 2)  # 3次元配列を作成
a =

ans(:,:,1) =

   1   3
   2   4

ans(:,:,2) =

   5   7
   6   8

a(2,1,2);   # (m == n)の場合: ans = 6
a(2,1);     # (m < n)の場合、インデクスは配列内
            # a(2,1,1)に等しい: ans = 2
a(2,4);     # (m < n)の場合、インデクスは配列の外側
            # 次元2と3は、サイズ2x2 = 4の新たな次元に折り畳まれる
            # 2行目[2, 4, 6, 8]の4番目の要素が選択される: ans = 8

インデクスの上級の使用法としては、1つの値で満たされた配列の作成があります。これはonesのインデクスをスカラー値に使用して行うことができます。結果はインデクス式の次元をもち、各要素が元のスカラーに等しいオブジェクトになります。たとえば以下の命令文

 
a = 13;
a(ones (1, 4))

これは4つの要素すべてが13のベクターを生成します。

同様に2つのonesベクターによりスカラーをインデクス付けすることにより、マトリクスを作成できます。以下の命令文

 
a = 13;
a(ones (1, 2), ones (1, 3))

これはすべての要素が13と等しい2x3のマトリクスを作成します。

最後の例は以下のように記述することもできます

 
13(ones (2, 3))

不要な乗算を避けることができるので、scalar * ones (N, M, …)とコードを構築するよりインデクス操作を使用するほうがより効果的です。さらに複製されるオブジェクトには乗算が定義されていないかもしれませんが、配列へのインデクス操作は常に定義されています。以下は、それ自身がスカラーではない基本ユニットから、2x3のセル配列を作成する方法を示します。

 
{"Hello"}(ones (2, 3))

ones (1, n)(onesの行ベクター)の結果は、(増分が0の)レンジとなることは注記しておくべきでしょう。内部的にレンジは開始値、増分、終値、値の合計として格納されます。したがって、要素数が4より大のときは常にonesのベクターまたはマトリクスのほうが、記憶領域にたいして効果的です。特に‘r’が行ベクターの場合、以下の式

 
  r(ones (1, n), :)
 
  r(ones (n, 1), :)

これは同じ結果を生成しますが、少なくとも‘r’と‘n’が十分大きければ、1つ目のほうが明らかに高速です。最初のケースでは、インデクスはOctaveが式を処理するためにより効果的なアルゴリズムを選択できるレンジ形式として、圧縮されて保持されます。

これらの違いを理解しないユーザーには、一般的に小さな配列を大きな配列に複製する場合は、関数repmatの使用を推奨します。

2つ目のインデクス操作の用途は、コードのスピードアップです。インデクス操作は高速な処理であり、慎重に使用することにより、特定の配列要素をループするような低速な処理の必要を低減できます。

以下のような値をもつ10要素の行ベクターaを作成する例で考えてみましょう a(i) = sqrt (i).

 
for i = 1:10
  a(i) = sqrt (i);
endfor

このようなループを使用してベクターを作成するのは、効果的ではありません。この場合は、以下のような式を使用するほうがより効果的でしょう

 
a = sqrt (1:10);

これはループ全体の使用を避けています。

ループを避けることができず、値の数が巨大なマトリクスの形成に結びついている場合、最初にマトリクスのサイズをセット(事前領域割り当て)してから、インデクスコマンドを使用して要素を挿入するほうが、一般的にはより高速です。たとえば、マトリクスaが与えられた場合、

 
[nr, nc] = size (a);
x = zeros (nr, n * nc);
for i = 1:n
  x(:,(i-1)*nc+1:i*nc) = a;
endfor

この式は、以下に比べてはるかに高速です

 
x = a;
for i = 1:n-1
  x = [x, a];
endfor

なぜなら、Octaveが中間結果を繰り返しリサイズする必要がないからです。

Function File: ind = sub2ind (dims, i, j)
Function File: ind = sub2ind (dims, s1, s2, …, sN)

添字を線形のインデクスに変換します。

以下は3行3列のマトリクスの2次元インデクス(2,3)を線形インデクスに変換する方法を示す例です。マトリクスは列から列へ、各列のすべての行が満たされるまで、線形にインデクス付けされます。

 
linear_index = sub2ind ([3, 3], 2, 3)
⇒ 8

See also: ind2sub.

Function File: [s1, s2, …, sN] = ind2sub (dims, ind)

線形のインデクスを添字に変換します。

以下は3行3列のマトリクスの線形インデクス8を添字に変換する方法を示す例です。マトリクスは列から列へ、各列のすべての行が満たされるまで、線形にインデクス付けされます。

 
[r, c] = ind2sub ([3, 3], 8)
    ⇒ r =  2
    ⇒ c =  3

See also: sub2ind.

Built-in Function: isindex (ind)
Built-in Function: isindex (ind, n)

indが有効なインデクスの場合は、trueをリターンします。有効なインデクスとは、正の整数(実際は実数データ型ですが)、または論理配列です。nが与えられた場合、それはインデクス付けされる次元の拡張の最大を指定します。可能なら結果は内部でキャッシュされるので、indを連続して使用する場合、再チェックを行いません。

Built-in Function: val = allow_noninteger_range_as_index ()
Built-in Function: old_val = allow_noninteger_range_as_index (new_val)
Built-in Function: allow_noninteger_range_as_index (new_val, "local")

非整数レンジをインデクスに使用できるかどうかを制御する内部変数にたいして、問い合わせまたはセットを行います。これはMATLABとの互換性にたいしては有用です。しかし、MATLABはレンジ式にたいして、異なるコンテキストで異なる扱いをするため、完全な互換性はありません。

関数内から"local"オプションとともに呼び出された場合、変数の変更はその関数および関数のサブルーチンにたいしてローカルになります。関数をexitするとき、変数の元の値がリストアされます。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.2 Calling Functions

関数(function)とは、特定の計算にたいする名前です。名前をもつので、プログラム内の任意の場所で名前で問い合わせることができます。たとえば、関数sqrtは数値の平方根を計算します。

関数のある固定されたセットはビルトインで、すべてのOctaveプログラム内でそれらを利用できることを意味します。sqrt関数は、そのうちの1つです。さらに、あなたが自分の関数を定義できます。これを行うための情報は、Functions and Scriptsを参照してください。

関数呼び出し式で関数を使用します。これは関数の後にカッコで括った引数リストを続けて構成されます。引数は、その関数が行うであろう計算のための、生の材料を与えます。2つ以上の引数がある場合は、カンマで区切ります。引数がない場合はカッコを省略できますが、関数呼び出しが意図されていることを明確に示すために、カッコを含めるのは良いアイデアです。以下にいくつか例を示します:

 
sqrt (x^2 + y^2)      # 引数=1
ones (n, m)           # 引数=2
rand ()               # 引数なし

関数はそれぞれ、特定の個数の引数を期待します。たとえばsqrt関数は平方根を求める数値を1つの引数として呼び出さなければなりません:

 
sqrt (argument)

ビルトイン関数には、可変個の引数をとるものがいくつかあります。引数の数は使い方に依存して異なり、与えられた引数の数に応じて異なった振る舞いをします。

他のすべての式と同様、関数呼び出しは値であり、値は与えられた引数に基づきその関数により計算されます。この例では、sqrt (argument)の値は、引数の平方根です。関数は、特定の変数に値を割り当てたり、入出力処理を行うような、副作用もあります。

他の多くの言語と異なり、Octaveの関数は複数の値をリターンします。たとえば、以下の命令文

 
[u, s, v] = svd (a)

これはマトリクスaのsingular value decompositionを3つの結果マトリクスusvに割り当てます。

複数代入式の左辺は、それ自体がリスト式であり、変数名リストまたはインデクス式を記述できます。Index ExpressionsAssignment Expressionsも参照してください。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.2.1 Call by Value

OctaveではFortranと異なり関数の引数は値で渡されます。これは関数に渡される前に関数呼び出しの各引数が評価されて、一時的な場所に割り当てられることを意味します。関数のパラメーターを値ではなく参照であると指定する方法は、現在のところありません。これは呼び出された関数内で直接関数パラメーターの値を変更することは不可能であることを意味します。関数ボディー内のローカルコピーだけが変更できます。たとえば、

 
function f (x, n)
  while (n-- > 0)
    disp (x);
  endwhile
endfunction

この関数は1つ目の引数をn回表示します。この関数では、呼び出された関数内で値が変更されることを心配しなくてもよい、一時的な変数として変数nを使用しています。値呼出しは最初にその関数がパラメーターの変更を試みないか判断する必要なく、常に定数を任意の関数パラメーターとすることができます。

呼び出し側は引数に変数として式を使用できますが、呼び出された関数はこれを知りません。知っているのは引数がもつ値だけです。たとえば、以下の関数呼び出しが与えられた場合

 
foo = "bar";
fcn (foo)

これを“変数foo”が引数だと考えるべきではありません。かわりに、引数を文字列値"bar"と考えるべきです。

たとえOctaveが関数の引数に値渡しのセマンティックを使用していても、不必要に値はコピーされません。たとえば、

 
x = rand (1000);
f (x);

この式は、関数fが引数を変更するまでは、実際に1000x1000のマトリクス要素2つが存在することを強いません。その後でOctaveは関数fのスコープ外で値が変更されたり、定数または一時的な結果値にたいする修正の試み(おそらく失敗します!)を避けるためにコピーを作成しなければならなくなります。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.2.2 Recursion

いくつかの制限(3)により、再帰関数呼び出しは許されません。再帰関数とは、直接または間接的に自身を呼び出す関数です。たとえば、以下は与えられた整数の階乗を計算する、非効率的(4)な方法の例です:

 
function retval = fact (n)
  if (n > 0)
    retval = n * fact (n-1);
  else
    retval = 1;
  endif
endfunction

この関数は自身を直接呼び出すので、再帰的です。これは呼び出すごとに、以前の呼び出しより1少ない引数を使用するので、最終的には終了します。一度引数が0以下になれば、自身を呼び出さず、再帰は終了します。

ビルトイン変数max_recursion_depthは、再帰の深さを制限し、Octaveが永久に再帰するのを防ぎます。

Built-in Function: val = max_recursion_depth ()
Built-in Function: old_val = max_recursion_depth (new_val)
Built-in Function: max_recursion_depth (new_val, "local")

関数が再帰的に呼び出される回数の内部制限にたいして、問い合わせまたはセットを行います。制限を超過した場合はエラーメッセージがプリントされ、制御はトップレベルに戻されます。

関数内から"local"オプションとともに呼び出された場合、変数の変更はその関数および関数のサブルーチンにたいしてローカルになります。関数をexitするとき、変数の元の値がリストアされます。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.3 Arithmetic Operators

以下の算術演算子が利用でき、それらはスカラーとマトリクスにたいして機能します。要素対要素の演算子と関数はブロードキャストします(Broadcastingを参照)。

x + y

加算。オペランドがどちらもマトリクスの場合、行数と列数が一致するか、同じ形体にブロードキャスト可能でなければならない。

x .+ y

要素ごとの加算。この演算子は+と等価。

x - y

減算。オペランドがどちらもマトリクスの場合は、行数と列数が一致するか、同じ形体にブロードキャスト可能でなければならない。

x .- y

要素ごとの減算。この演算子は-と等価。

x * y

マトリクスの乗算。xの列数は、yの行数に一致するか、同じ形体にブロードキャスト可能でなければならない。

x .* y

要素ごとのの乗算。オペランドがどちらもマトリクスの場合は、行数と列数が一致するか、同じ形体にブロードキャスト可能でなければならない。

x / y

右除算。これは以下の式と概念的に等価

 
(inverse (y') * x')'

しかしy’を逆転せずに計算される。

システムがsquareeではない、または係数行列が非正則の場合は、minimum norm solutionが計算されます。

x ./ y

要素ごとの右除算。

x \ y

左除算。これは以下の式と概念的に等価

 
inverse (x) * y

しかしxを逆転せずに計算される。

システムがsquareeではない、または係数行列が非正則の場合は、minimum norm solutionが計算されます。

x .\ y

要素ごとの左除算。yの各要素は、対応するxの要素により除される。

x ^ y
x ** y

べき乗演算子。xyがどちらもスカラーの場合、この演算子はxy乗じてリターンする。xがスカラーでyが正方マトリクスの場合、結果は固有値展開を使用して計算される。xが正方マトリクスの場合、yが整数なら結果は乗算を繰り返して計算され、yが非整数なら固有値展開により計算される。xyが両方マトリクスなら結果はエラーとなる。

この演算子の実装は改善される必要がある。

x .^ y
x .** y

要素ごとのべき乗演算子。オペランドがどちらもマトリクスの場合、行数と列数が一致するか、同じ形体にブロードキャストされなければならない。複素数の結果が複数利用できる場合、最小の非負(angle)の引数が採用される。このルールにより、たとえ実数の根が利用できても、複素数の根がリターンされる。実数の結果を望むならrealpowrealsqrtcbrtnthrootを使用すること。

-x

Negation.

+x

単項プラス。この演算子はオペランドに影響を与えない。

x

複素数の共役転置。実数の引数にたいして、この演算子は転置演算子と等価。複素数引数にたいして、この演算子は以下の式と等価

 
conj (x.')
x.’

転置。

Octaveの要素ごとの演算子は‘.’で始まり、以下のような文にたいして曖昧さが存在することに注意してください

 
1./m

なぜならピリオドは定数の一部、あるいは演算子の一部としてどちらにも解釈できるからです。この競合を解決するために、Octaveはあたかも以下をタイプしたかのように扱い

 
(1) ./ m

以下のように扱うことはありません

 
(1.) / m

これは、与えられた任意の位置において最長のマッチが優先されるというOctave字句解析の通常の振る舞いと統一が取れませんが、この場合はこちらのほうが便利です。

Built-in Function: ctranspose (x)

複素数のxの共役転置をリターンします。この関数とx'は等価です。

See also: transpose.

Built-in Function: ldivide (x, y)

xyの要素ごとの左除算をリターンします。この関数とx .\ yは等価です。

See also: rdivide, mldivide, times, plus.

Built-in Function: minus (x, y)

この関数はx - yと等価です。

See also: plus, uminus.

Built-in Function: mldivide (x, y)

xyの左除算マトリクスをリターンします。この関数はx \ yと等価です。

See also: mrdivide, ldivide, rdivide.

Built-in Function: mpower (x, y)

xy乗というべき乗操作を行いマトリクスをリターンします。この関数はx ^ yと等価です。

See also: power, mtimes, plus, minus.

Built-in Function: mrdivide (x, y)

xyを右除算したマトリクスをリターンします。この関数はx / yと等価です。

See also: mldivide, rdivide, plus, minus.

Built-in Function: mtimes (x, y)
Built-in Function: mtimes (x1, x2, …)

入力のmultiplication productをリターンします。この関数とx * yは等価です。より多くの引数が与えられた場合、multiplicationは累積的に左から右へと行われます:

 
(…((x1 * x2) * x3) * …)

少なくとも1つの引数が要求されます。

See also: times, plus, minus, rdivide, mrdivide, mldivide, mpower.

Built-in Function: plus (x, y)
Built-in Function: plus (x1, x2, …)

この関数はx + yと等価です。より多くの引数が与えられた場合、加算は左から右へ累積的に行われます:

 
(…((x1 + x2) + x3) + …)

少なくとも1つの引数が要求されます。

See also: minus, uplus.

Built-in Function: power (x, y)

要素ごとにxy乗してリターンします。複数の複素数結果が利用できる場合は、最小の非負(angle)の引数をリターンします。実数の結果が望ましい場合はrealpowrealsqrtcbrtnthrootを使用してください。

この関数はx .^ yと等価です。

See also: mpower, realpow, realsqrt, cbrt, nthroot.

Built-in Function: rdivide (x, y)

xyを要素ごとに右除算してリターンします。この関数はx ./ yと等価です。

See also: ldivide, mrdivide, times, plus.

Built-in Function: times (x, y)
Built-in Function: times (x1, x2, …)

入力の要素ごとのmultiplication productをリターンします。この関数とx .* yは等価です。より多くの引数が与えられた場合、乗算は左から右に累積的に適用されます:

 
(…((x1 .* x2) .* x3) .* …)

少なくとも1つの引数が要求されます。

See also: mtimes, rdivide.

Built-in Function: transpose (x)

xの転置をリターンします。この関数とx.'は等価です。

See also: ctranspose.

Built-in Function: uminus (x)

この関数は- xと等価です。

See also: uplus, minus.

Built-in Function: uplus (x)

この関数は+ xと等価です。

See also: uminus, plus, minus.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.4 Comparison Operators

比較演算子は等価性のような関連について数値を比較します。これらは関係演算子を用いて記述されます。

Octaveのすべての比較演算子は、比較がtrueなら1、falseなら0をリターンします。マトリクス値にたいしては、すべて要素ごとの原理に基づき機能します。ブロードキャストのルールが適用されます。Broadcastingを参照してください。たとえば:

 
[1, 2; 3, 4] == [1, 3; 2, 4]
     ⇒  1  0
         0  1

ブロードキャストのルールにしたがい、オペランドの1つがスカラーで、もう一方がマトリクスの場合は、そのスカラーがマトリクスの各要素と順に比較され、結果はそのマトリクスと同じサイズになります。

x < y

xyより小ならtrue。

x <= y

xy以下ならtrue。

x == y

xyと等しければtrue。

x >= y

xy以上ならtrue。

x > y

xyより大ならtrue。

x != y
x ~= y

xyとしくなければtrue。

複素数値にたいしては以下の順序が定義されている(z1 < z2の場合に限る)。

 
  abs (z1) < abs (z2) 
  || (abs (z1) == abs (z2) && arg (z1) < arg (z2))

これはmaxminsortで使用される順序と整合がとれていますが、実数部だけを比較するMATLABとは不整合です。

文字列の比較は上記にリストした演算子ではなく、strcmp関数により処理されます。Stringsを参照してください。

Built-in Function: eq (x, y)

2つの入力が等しければtrueをリターンします。この関数はx == yと等価です。

See also: ne, isequal, le, ge, gt, ne, lt.

Built-in Function: ge (x, y)

この関数はx >= yと等価です。

See also: le, eq, gt, ne, lt.

Built-in Function: gt (x, y)

この関数はx > yと等価です

See also: le, eq, ge, ne, lt.

Function File: isequal (x1, x2, …)

x1x2、…がすべて等しければtrueをリターンします。

See also: isequaln.

Function File: isequaln (x1, x2, …)

NaN == NaNという追加の仮定のもとに、x1x2、…のすべてが等しければtrueをリターンします(データセット内のNaNの代替物の比較は行いません)。

See also: isequal.

Built-in Function: le (x, y)

この関数はx <= yと等価です。

See also: eq, ge, gt, ne, lt.

Built-in Function: lt (x, y)

この関数はx < yと等価です。

See also: le, eq, ge, gt, ne.

Built-in Function: ne (x, y)

2つの入力が等しくなければtrueをリターンします。この順序はx != yと等価です。

See also: eq, isequal, le, ge, lt.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.5 Boolean Expressions


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.5.1 Element-by-element Boolean Operators

要素ごとの論理式は、ネストを制御するカッコとともにブール演算子“or” (‘|’)、“and” (‘&’)、“not” (‘!’)を使用します。ブール式のtrueはコンポーネント式の対応する要素の論理値を組み合わせて計算されます。値が0の場合はfalse、それ以外はtrueと判断されます。

要素ごとのブール式は、比較式が使える場所ならどこでも使用できます。これらifwhileなどの命令文内で使用されます。しかしifwhileなどの命令文内の条件としてマトリクス値が使用される場合は、マトリクスのすべての要素が非0のときだけtrueになります。

比較演算子と同様、要素ごとのブール式は数値(1はtrue、0はfalse)をもち、ブール式の結果をを変数に格納したり、数学的に使用された場合に効果を発揮します。

以下は3つの要素ごとのブール演算子の説明です。

boolean1 & boolean2

対応する要素boolean1boolean2の両方がtrueのとき、結果要素はtrue。

boolean1 | boolean2

対応する要素boolean1boolean2のどちらか一方がtrueのとき、結果要素はtrue。

! boolean
~ boolean

対応する要素booleanがfalseのとき、結果要素はtrue。

これらの演算子は、要素ごとの原理にもとづき機能します。たとえば、以下の式

 
[1, 0; 0, 1] & [1, 0; 2, 3]

は2行2列の単位マトリクスをリターンします。

2項演算子にたいしては、ブロードキャストルールが適用されます。Broadcastingを参照してください。特にオペランドの1つがスカラーで、もう一方がマトリクスの場合、しの演算子はスカラーとマトリクスの各要素に適用されます。

要素ごとの2項ブール演算子にたいしては、結果を計算する前に部分式boolean1boolean2が評価されます。。これは、式が副作用をもつとき、違いを生じます。たとえば、以下の式

 
a & b++

これは、たとえaが0でも、変数bの値はインクリメントされます。

この振る舞いは説明したように、マトリクス値をもつオペランドにたいしてブール演算子が機能するために必要なのです。

Built-in Function: and (x, y)
Built-in Function: and (x1, x2, …)

xyの論理的ANDをリターンします。この関数はx & yと等価です。より多くの引数が与えられた場合、論理的ANDは左から右へと累積的に適用されます:

 
(…((x1 & x2) & x3) & …)

少なくとも1つの引数が要求されます。

See also: or, not, xor.

Built-in Function: not (x)

xの論理的NOTをリターンします。この関数は! xと等価です。

See also: and, or, xor.

Built-in Function: or (x, y)
Built-in Function: or (x1, x2, …)

xyの論理的ORをリターンします。この関数はx | yと等価です。より多くの引数が与えられた場合、論理的ORは左から右へと累積的に適用されます:

 
(…((x1 | x2) | x3) | …)

少なくとも1つの引数が要求されます。

See also: and, not, xor.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.5.2 Short-circuit Boolean Operators

ifwhileの中での暗黙的なスカラー値への変換と組み合わせれば、Octaveの要素ごとのブール演算子は、論理演算の大部分を処理するのに十分です。しかし、全体の論理値が判断されたらすぐにブール式の評価を停止するのが望ましい場合もあります。Octaveのブール演算子のショートサーキットは、この方法で機能します。

boolean1 && boolean2

boolean1は、all (boolean1(:))と等価な処理を使用して、スカラーに評価・変換されます。これがfalseの場合、式全体の結果は0になります。trueの場合、式boolean2all (boolean1(:))と等価な処理を使用して、スカラーへと評価・変換されます。trueの場合、式全体の結果は1になります。それ以外は、式全体の結果は0になります。

警告: all (boolean1(:))の評価ルールには、boolean1が空マトリクスの場合に、1つの例外があります。空マトリクスの論理値は空マトリクスにたいして常にfalseなので、たとえall ([])trueでも、[] && truefalseに評価されます。

boolean1 || boolean2

boolean1は、all (boolean1(:))と等価な処理を使用して、スカラーに評価・変換されます。trueの場合、式全体の結果は1になります。falseの場合、all (boolean1(:))と等価な処理を使用して、式boolean2がスカラーに評価・変換されます。trueの場合、式全体の結果は1になります。それ以外は、式全体の結果は0になります。

警告: 空マトリクスの論理値は常にfalseになります。詳細は上記リストのアイテムを参照してください。

式全体の論理値が決定される前に両方のオペランドが評価されることはないという事実は重要です。たとえば、以下の式

 
a && b++

変数aが非0の場合のみ、変数bの値はインクリメントされます。

これは、より簡潔なコードを記述するのに使用できます。たとえば、

 
function f (a, b, c)
  if (nargin > 2 && ischar (c))
    …

存在しない引数の評価を避けるために2つのif文を使用するかわりに、上記のように記述することが可能です。たとえば、ショートサーキット機能がなければ、以下のように記述する必要があるでしょう

 
function f (a, b, c)
  if (nargin > 2)
    if (ischar (c))
      …

以下のように記述すると

 
function f (a, b, c)
  if (nargin > 2 & ischar (c))
    …

fが1つ、または2つの引数で呼び出された場合にエラーとなります。なぜならOctaveは演算子‘&’にたいして、両方のオペランドの評価を強いるからです。

MATLABは、ifおよびwhile文の論理式内で使用されたとき、演算子‘&’と‘|’がショートサーキットのために特別に振る舞うことを許しています。Octaveパーサーもおそらく同じ振る舞いを指示するでしょうが、この使用法は推奨されません。

Built-in Function: val = do_braindead_shortcircuit_evaluation ()
Built-in Function: old_val = do_braindead_shortcircuit_evaluation (new_val)
Built-in Function: do_braindead_shortcircuit_evaluation (new_val, "local")

ifまたはwhile文の条件部の内部で、‘|’および‘&’演算子が評価のショートサーキットを行うかどうかを制御する内部変数にたいして、問い合わせまたはセットを行います。

この機能はMATLABとの互換性のためだけに提供されており、この機能にもとづいた古いコードを移植するのでなければ、使用するべきではありません。

新しいプログラムで論理式のショートサーキット動作を得るには、常に‘&&’および‘||’演算子を使用するべきです。

関数内から"local"オプションとともに呼び出された場合、変数の変更はその関数および関数のサブルーチンにたいしてローカルになります。関数をexitするとき、変数の元の値がリストアされます。

最期に、Octaveでは三項演算子(?:)はサポートされません。ショートサーキットが重要でなければ、ifelse関数で置き換えることができます。

Built-in Function: merge (mask, tval, fval)
Built-in Function: ifelse (mask, tval, fval)

maskの値に応じて、true_valfalse_valの要素をマージします。maskが論理的スカラーの場合、他の2つの引数は任意の値をとることができます。それ以外は、maskは論理的配列でなければならず、tvalfvalはマッチングするクラスかセル配列です。スカラーマスクの場合、maskがtrueならtvalがリターンされ、それ以外はfvalがリターンされます。

配列マスクの場合、tvalfvalはどちらもスカラーか、maskと次元が等しい配列でなければなりません。以下のように結果が構築されます:

 
result(mask) = tval(mask);
result(! mask) = fval(! mask);

maskは任意の数値型でもよく、この場合は最初に論理値に変換されます。

See also: logical, diff.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.6 Assignment Expressions

割り当てとは、変換に新しい値を格納することです。たとえば、以下の式は変数zに値1を代入します:

 
z = 1

この式が実行されると、変数zは値1をもちます。zの古い値が何であれ、以前に割り当てられていた値は忘れられます。‘=’記号は、代入演算子と呼ばれます。

代入により文字列値も格納できます。たとえば、以下の式は変数messageに値"this food is good"を格納します:

 
thing = "food"
predicate = "good"
message = [ "this " , thing , " is " , predicate ]

(これは文字列の連結も示しています。)

大部分の演算子(追加、連結など)は、値の計算以外の効果はもちません。値が不要なら、演算子を使用することもないでしょう。代入演算子は異なります。これは値を生成しますが、たとえ値を無視しても、変数の変更により代入は効果をもちます。これを副作用と呼びます。

代入の左辺のオペランドは、変数である必要はありません(Variablesを参照)。マトリクスの要素(Index Expressionsを参照)や、リターン値のリスト(Calling Functionsを参照)でも可能です。これらはすべて左辺値(lvalues)と呼ばれ、これはそれらが代入演算子の左辺に出現することを意味します。右辺のオペランドは任意の式です。これは新しい値を生成して、代入により指定された変数、マトリクス要素、リターン値リストに格納されます。

変数が不変の型をもたないことに注意するのが重要です。値が何であれ、そのとき保持する型が、変数の型です。以下のプログラム断片では、変数fooは最初数値をもち、その後文字列値をもちます:

 
octave:13> foo = 1
foo = 1
octave:13> foo = "bar"
foo = bar

2つ目の代入によりfooに文字列値が与えられると、以前は数値をもっていたという事実は忘れられます。

インデクス付けされたマトリクスにスカラーを代入すると、インデクスにより参照されていた要素すべてにスカラー値がセットされます。たとえば、aが少なくとも2つの列をもつマトリクスの場合

 
a(:, 2) = 5

これはaに2列目の要素すべてに5をセットします。

多くに場合、空マトリクス‘[]’を割り当てることにより、マトリクスまたはベクターの行や列のすべてを削除できます。Empty Matricesを参照してください。たとえば4行5列のマトリクスAが与えられたとき、

 
A (3, :) = []

この代入により、Aの3行目が削除され、

 
A (:, 1:2:5) = []

この割り当てでは、1つ目、3つ目、5つ目の列が削除されます。

代入は式なので値をもちます。したがz = 1は式として値1をもちます。この結果、以下のように複数の代入を一緒に記述できます:

 
x = y = z = 0

これは3つの変数すべてに0をセットします。なぜならz = 0の値は0で、それがyに格納され、y = z = 0の値も0で、それがxに格納されるからです。

これはリスト値への代入でも真なので、以下は有効な式です

 
[a, b, c] = [u, s, v] = svd (a)

これは以下とまったく同じです

 
[u, s, v] = svd (a)
a = u
b = s
c = v

このような式では、式の各部分の値数がマッチする必要はありません。たとえば、以下の式

 
[a, b] = [u, s, v] = svd (a)

は以下と等価です

 
[u, s, v] = svd (a)
a = u
b = s

しかし式の左辺の値の数は、右辺の値の数を超えることはできません。たとえば、以下はエラーを生成します。

 
[a, b, c, d] = [u, s, v] = svd (a);
-| error: element number 4 undefined in return list

シンボル~は左辺値リストの代替えとして使用され、対応するリターン値は無視され、どこにも格納されないことを示します:

 
[~, s, v] = svd (a);

ダミー変数を使用することにより、より明解になり、メモリーも効率的になります。右辺の式にたいするnargoutの値は影響を受けません。代入が式として使用された場合、リターン値は無視する値が省かれたカンマ区切りリストになります。

とても一般的なプログラミングのパターンに、以下のように与えられた値による既存変数のインクリメントがあります

 
a = a + 2;

以下のように+=演算子を使えば、より明解・簡略に記述できます

 
a += 2;

同様な演算子は減算(-=)、乗算(*=)、除算(/=)にも存在します。以下の形式の式

 
expr1 op= expr2

は以下と等価です

 
expr1 = (expr1) op (expr2)

ここで、expr2が副作用をもたないシンプルな式であれば、op+-*/のうちの1つです。expr2も代入演算子を含む場合、この式は以下のように評価されます

 
temp = expr2
expr1 = (expr1) op temp

ここでtempexpr2を評価することにより計算された一時的な値を格納するプレースホルダーです。したがって以下の式

 
a *= b+1

は以下と等価です

 
a = a * (b+1)

以下のようにはなりません

 
a = a * b + 1

式が呼び出される場所ならどこでも、代入を使用できます。たとえば、yに1をセットしてからxが1と等しいかテストするために、x != (y = 1)と記述するのは有効です。しかし、このスタイルはプログラムの読解を難しくする傾向があります。使い捨てのプログラムを除き、このようなネストした代入を取り除くように書き直すべきです。これは難しいことではありません。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.7 Increment Operators

インクリメント演算子は、変数の値を1増加または減少させます。変数を増加させる演算子は‘++’と記述します。この演算子は、変数から値を取得する前、または後のどちらかで変数を増加させるために使用します。

たとえば変数xを事前に増加させるには、++xと記述します。これはxに1加算してから、式の結果としてxの新しい値をリターンします。これは式x = x + 1とまったく同じです。

変数xを事後に増加させるには、x++と記述します。これはxに1加算しますが、xが増加される前にもっていた値をリターンします。たとえば、xが2に等しい場合、式x++の結果は2で、xの新たな値は3になります。

マトリクスおよびベクターの引数については、インクリメントおよびデクリメント演算子はオペランドの各要素に機能します。

以下はすべてのインクリメントおよびデクリメント式のリストです。

++x

この式は、変数xをインクリメントします。式の値はx新しい値です。これは式x = x + 1と等価です。

--x

この式は、変数xをデクリメントします。式の値はx新しい値です。これは式x = x - 1と等価です。

x++

この式は変数xをインクリメントします。式の値は、x古い値です。

x--

この式は、変数xをデクリメントします。式の値はx古い値です。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.8 Operator Precedence

演算子の優先順位は、1つの式中に異なる演算子が近接して出現するとき、演算子がどのようにグループ化されるかを決定します。たとえば‘*’は‘+’より高い優先順位をもちます。したがって式a + b * cbcを乗じてから、その積にaを和することを意味します(例: a + (b * c))。

カッコを使用することにより、演算子の優先順位を変更できます。優先順位は、あなたがカッコを書かなかったとき、どこにカッコがあるとみなすか告げるものと考えることができます。実際のところ、通常とは異なる演算子を組み合わせるときは常にカッコを使用するのが賢明です。なぜならプログラムを読む他の人は、この場合何が優先されるのか覚えていないかもしれないからです。あなたも同様に忘れるかもしれず、間違えるかもしれません。明示的なカッコは、そのような間違いを防ぐ助けになります。

イコール演算子の優先順位が一緒に使用された場合、最左演算子が最初にグループ化されますが、代入演算子は逆順にグループ化されます。したがって式a - b + c(a - b) + cとグループ化されますが、a = b = ca = (b = c)のようにグループ化されます。

前置単項演算子の優先順位は、オペランドの後に他の演算子が続く場合に重要です。たとえば-x^2-(x^2)を意味します。なぜなら‘-’は‘^’より優先順位が低いからです。

以下はOctaveでの演算子を優先順位順に並べたテーブルです。しかしすべての演算子が左から右にグループ化されるわけではないことに注意してください。

関数呼び出し、および配列のインデクス操作、セル配列のインデクス操作、および構造体要素のインデクス操作

()’ ‘{}’ ‘.

後置インクリメント、および後置デクリメント

++’ ‘--

これらの演算子は右から左にグループ化されます。

転置、および指数

'’ ‘.'’ ‘^’ ‘**’ ‘.^’ ‘.**

単項プラス、単項マイナス、前置インクリメント、前置デクリメント、論理的"not"

+’ ‘-’ ‘++’ ‘--’ ‘~’ ‘!

乗算および除算

*’ ‘/’ ‘\’ ‘.\’ ‘.*’ ‘./

加算、減算

+’ ‘-

コロン

:

比較

<’ ‘<=’ ‘==’ ‘>=’ ‘>’ ‘!=’ ‘~=

要素ごとの"and"

&

要素ごとの"or"

|

論理的"and"

&&

論理的"or"

||

代入

=’ ‘+=’ ‘-=’ ‘*=’ ‘/=’ ‘\=’ ‘^=’ ‘.*=’ ‘./=’ ‘.\=’ ‘.^=’ ‘|=’ ‘&=

これらの演算子は右から左にグループ化されます。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9. Evaluation

式を評価するには通常、Octaveプロンプトでシンプルにそれらをタイプするか、ファイルに保存したコマンドの解釈をOctaveに命令します。

計算されて文字列に格納だれた式の評価が必要なときがあるかもしれません。それはまさにeval関数が行うことです。

Built-in Function: eval (try)
Built-in Function: eval (try, catch)

文字列tryをパースして、それがOctaveプログラムであるかのように評価します。失敗した場合は、オプション文字列catchを評価します。文字列tryはカレントコンテキストで評価されるので、evalがリターンした後でも結果を利用できます。

以下はカレントワークスペースで値が約3.1416の変数Aを作成する例です。

 
eval ("A = acos(-1);");

tryを評価する間にエラーが発生した場合は、以下の例が示すようにcatch文字列が評価されます:

 
eval ('error ("This is a bad example");',
      'printf ("This error occurred:\n%s\n", lasterr ());');
     -| This error occurred:
        This is a bad example

プログラミングノート: evalを任意文字列の実行ではなくエラーキャプチャリングメカニズムとしてだけ使用する場合はかわりにtry/catchブロックかunwind_protect/unwind_protect_cleanupの使用を考えてください。これらのテクニックは高いパフォーマンスをもち、任意のコードを評価することによるセキュリティ問題は発生しません。

See also: evalin.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.1 Calling a Function by its Name

feval関数により関数名を含む文字列から関数を実行できます。これはユーザー提供関数を呼び出す必要のある関数の記述に便利です。feval関数は呼び出す関数の名前を1つ目お引数にとり、残りの引数はその関数に渡されます。

以下はfevalを使用して、ニュートン法により1変数のユーザー提供関数の根を見つける簡単な関数の例です。

 
function result = newtroot (fname, x)

# usage: newtroot (fname, x)
#
#   fname : a string naming a function f(x).
#   x     : initial guess

  delta = tol = sqrt (eps);
  maxit = 200;
  fx = feval (fname, x);
  for i = 1:maxit
    if (abs (fx) < tol)
      result = x;
      return;
    else
      fx_new = feval (fname, x + delta);
      deriv = (fx_new - fx) / delta;
      x = x - fx / deriv;
      fx = fx_new;
    endif
  endfor

  result = x;

endfunction

これは単にユーザー提供関数を呼び出す例を意図したもので、あまりシリアスにとるべきではないことに注意してください。さらに、より頑健なアルゴリズムを使用することにより、シリアスなコードは、提供された関数が実際に関数なのか等、すべての引数の数や型をチェックするでしょう。数値オブジェクトにたいする述語についてはPredicates for Numeric Objectsexist関数の説明はStatus of Variablesを参照してください。

Built-in Function: feval (name, …)

nameという名前の関数を評価します。、2つ目以降の引数は、名前付き関数の入力として渡されます。たとえば、

 
feval ("acos", -1)
     ⇒ 3.1416

これは引数‘-1’で関数acosを呼び出します。

関数fevalは任意の種類の関数ハンドルとともに使用することもできます。歴史的に、fevalは文字列内のユーザー提供関数を呼び出す唯一の方法でしたが、現在はより明快な構文を提供する関数ハンドルが好まれます。たとえば、

 
f = @exp;
feval (f, 1)
    ⇒ 2.7183
f (1)
    ⇒ 2.7183

これは同じ方法でfにより参照される関数を呼び出します。fが関数ハンドル、文字列内の関数名、またはインライン関数なのか事前に予測できない場合は、かわりにfevalを使用してください。

ユーザースクリプトファイルを呼び出す同様の関数runもあります。スクリプトファイルはユーザーのパス上にある必要はありません。

Command: run script
Function File: run ("script")

カレントワークスペース内のscriptを実行します。

Octaveのロードパスに指定されたディレクトリに存在し、拡張子が‘".m"’のスクリプトは、単に名前をタイプして実行できます。ロードパス上にないスクリプトにたいしては、runを使用します。

ファイル名scriptはファイル名のみ、完全ファイル名または相対ファイル名で指定してもよく、拡張子を付けても付けなくても構いません。拡張子が指定されない場合、Octaveは拡張子なしのファイル名にフォールバックする前に、まず拡張子‘".m"’のスクリプトを検索します。

実装ノート: scriptがパスコンポーネントを含む場合、runはまずscriptを探すディレクトリにディレクトリを変更します。その後runはスクリプトを実行して、元のディレクトリにリターンします。

See also: path, addpath, source.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.2 Evaluation in a Different Context

式を評価する前に式内で使用されている変数の値を置き換える必要があります。これらはシンボルテーブルに格納されています。インタープリターが新たに関数を開始するときは常にカレントシンボルテーブルを保存してから新しいシンボルテーブルを作成し、それを関数パラメーターのリストとnarginのような事前定義された変数を初期化します。関数内の式は、新しいシンボルテーブルを使用します。

呼び出したときに、あなたのコンテキスト内の変数を変更するような関数を記述したいときがあります。これによりCのゆなプログラミング言語でのポインター使用に似た、名前渡しスタイルの関数を使用できます。

m-filesのsaveloadを行う関数を記述する方法を考えてみましょう。たとえば:

 
function create_data
  x = linspace (0, 10, 10);
  y = sin (x);
  save mydata x y
endfunction

evalinにより、以下のようにsaveを記述できます:

 
function save (file, name1, name2)
  f = open_save_file (file);
  save_var (f, name1, evalin ("caller", name1));
  save_var (f, name2, evalin ("caller", name2));
endfunction

ここで‘caller’はcreate_data関数、name1xを評価されますした値である文字列"x"です。

後で異なるコンテキストでmydataから値をloadしたい場合

 
function process_data
  load mydata
  … do work …
endfunction

assigninにより、以下のようにloadを記述できます:

 
function load (file)
  f = open_load_file (file);
  [name, val] = load_var (f);
  assignin ("caller", name, val);
  [name, val] = load_var (f);
  assignin ("caller", name, val);
endfunction

ここで‘caller’はprocess_data関数です。

コマンドプロンプトで‘caller’ではなくコンテキスト‘base’で変数のセットおよび使用ができます。

これらの関数が実際に使用されるのはまれです。1つの例としてfail (‘code’, ‘pattern’)関数があります。これは呼び出し側のコンテキストで‘code’を評価して、与えられたパターンにマッチするエラーメッセージをチェックします。他のsaveloadのような例はC++で記述されており、Octave変数はすべて‘caller’のコンテキストにあり、evalinは必要ありません。

Built-in Function: evalin (context, try)
Built-in Function: evalin (context, try, catch)

式が"caller""base"どちらか一方のコンテキストcontextで評価されることを除外すれば、evalと同様です。

See also: eval, assignin.

Built-in Function: assignin (context, varname, value)

"base""caller"どちらか一方のコンテキストcontextで、varnamevalueを代入します。

See also: evalin.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10. Statements

命令文シンプルな定数式、ネストされたループの複雑なリスト、条件文などです。

ifwhileなどの制御文は、Octaveプログラムの実行において、フロー制御を行います。制御文は、単なる式と区別するために、すべてifwhileなどの特殊キーワードで始まります。制御文の多くは他の命令文を含みます。たとえばif文は、それが実行されるか、されないかは別として、他の命令文を含みます。

制御文は、その制御文の終わりをマークするために、対応するend文をもちます。たとえば、キーワードendifif文の終わりをマークし、endwhilewhile文の終わりをマークします。これらの特定的なendキーワードを使える場所ではキーワードendも使うことができますが、、より特定的なキーワードを使用することにより、Octaveはendトークンのミスマッチや欠落にたいして、より良い診断情報を提供できます。

命令文のリストにはifwhileのようなキーワードから、制御文のボディーから呼び出される対応するend命令が含まれます。


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.1 The if Statement

if文は、Octaveにおける意思決定のための命令文です。if文には、3つの形式があります。もっとも簡単なのは、以下のような形式です:

 
if (condition)
  then-body
endif

conditionは、残りの命令文が実行されるかを制御する式です。conditionがtrueのときだけ、then-bodyが実行されます。

if文中の条件は、値が非0のときはtrue、0のときはfalseと判定されます。if文中の条件式の値がベクターかマトリクスの場合は、それらが空でなく、すべての要素が非0のときだけtrueと判定されます。

if文の2つ目は以下のような形式です:

 
if (condition)
  then-body
else
  else-body
endif

conditionがtrueのときはthen-bodyが実行され、それ以外はelse-bodyが実行されます。

以下は例です:

 
if (rem (x, 2) == 0)
  printf ("x is even\n");
else
  printf ("x is odd\n");
endif

この例では、式rem (x, 2) == 0がtrue(つまりxの値が2で割り切れる)の場合は1つ目のprintf文が評価され、それ以外は2つ目のprintf文が評価されます。

if文の3つ目、そしてもっとも一般的な形式では、1つの命令文の中で、複数の判定を組み合わせることができます。これは以下のようなものです:

 
if (condition)
  then-body
elseif (condition)
  elseif-body
else
  else-body
endif

任意の数のelseif節を記述できます。各条件は順番にテストされ、trueになる条件が見つかったら、その条件に対応するbodyが実行されます。trueとなる条件がない場合、else節が与えられたときは、それのbodyが実行されます。else節は1つだけ記述でき、命令文の最後の部分に記述しなければなりません。

以下の例では、1つ目の条件がtrue(つまりxの値が2で割り切れる)の場合は、1つ目のprintf文が実行されます。falseの場合は2つ目の条件がテストされ、それがtrue(つまりxの値が3で割り切れる)の場合は、2つ目のprintf文が実行されます。それ以外は、3つ目のprintf文が実行されます。

 
if (rem (x, 2) == 0)
  printf ("x is even\n");
elseif (rem (x, 3) == 0)
  printf ("x is odd and divisible by 3\n");
else
  printf ("x is odd\n");
endif

キーワードelseifは、Fortranのようにelse ifと記述してはならないことに注意してください。そのように記述した場合、elseifの間のスペースは、別のif文のelse節にある新たなif命令文としてそれを扱うようOctaveに指示します。たとえば、以下のように記述した場合

 
if (c1)
  body-1
else if (c2)
  body-2
endif

Octave will expect additional input to complete the first if statement. If you are using Octave interactively, it will continue to prompt you for additional input. If Octave is reading this input from a file, it may complain about missing or mismatched end statements, or, if you have not used the more specific end statements (endif, endfor, etc.), it may simply produce incorrect results, without producing any warning messages.

It is much easier to see the error if we rewrite the statements above like this,

 
if (c1)
  body-1
else
  if (c2)
    body-2
  endif

using the indentation to show how Octave groups the statements. See section Functions and Scripts.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.2 The switch Statement

It is very common to take different actions depending on the value of one variable. This is possible using the if statement in the following way

 
if (X == 1)
  do_something ();
elseif (X == 2)
  do_something_else ();
else
  do_something_completely_different ();
endif

This kind of code can however be very cumbersome to both write and maintain. To overcome this problem Octave supports the switch statement. Using this statement, the above example becomes

 
switch (X)
  case 1
    do_something ();
  case 2
    do_something_else ();
  otherwise
    do_something_completely_different ();
endswitch

This code makes the repetitive structure of the problem more explicit, making the code easier to read, and hence maintain. Also, if the variable X should change its name, only one line would need changing compared to one line per case when if statements are used.

The general form of the switch statement is

 
switch (expression)
  case label
    command_list
  case label
    command_list
  …

  otherwise
    command_list
endswitch

where label can be any expression. However, duplicate label values are not detected, and only the command_list corresponding to the first match will be executed. For the switch statement to be meaningful at least one case label command_list clause must be present, while the otherwise command_list clause is optional.

If label is a cell array the corresponding command_list is executed if any of the elements of the cell array match expression. As an example, the following program will print ‘Variable is either 6 or 7’.

 
A = 7;
switch (A)
  case { 6, 7 }
    printf ("variable is either 6 or 7\n");
  otherwise
    printf ("variable is neither 6 nor 7\n");
endswitch

As with all other specific end keywords, endswitch may be replaced by end, but you can get better diagnostics if you use the specific forms.

One advantage of using the switch statement compared to using if statements is that the labels can be strings. If an if statement is used it is not possible to write

 
if (X == "a string") # This is NOT valid

since a character-to-character comparison between X and the string will be made instead of evaluating if the strings are equal. This special-case is handled by the switch statement, and it is possible to write programs that look like this

 
switch (X)
  case "a string"
    do_something
  …
endswitch

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.2.1 Notes for the C Programmer

The switch statement is also available in the widely used C programming language. There are, however, some differences between the statement in Octave and C


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.3 The while Statement

In programming, a loop means a part of a program that is (or at least can be) executed two or more times in succession.

The while statement is the simplest looping statement in Octave. It repeatedly executes a statement as long as a condition is true. As with the condition in an if statement, the condition in a while statement is considered true if its value is non-zero, and false if its value is zero. If the value of the conditional expression in a while statement is a vector or a matrix, it is considered true only if it is non-empty and all of the elements are non-zero.

Octave’s while statement looks like this:

 
while (condition)
  body
endwhile

Here body is a statement or list of statements that we call the body of the loop, and condition is an expression that controls how long the loop keeps running.

The first thing the while statement does is test condition. If condition is true, it executes the statement body. After body has been executed, condition is tested again, and if it is still true, body is executed again. This process repeats until condition is no longer true. If condition is initially false, the body of the loop is never executed.

This example creates a variable fib that contains the first ten elements of the Fibonacci sequence.

 
fib = ones (1, 10);
i = 3;
while (i <= 10)
  fib (i) = fib (i-1) + fib (i-2);
  i++;
endwhile

Here the body of the loop contains two statements.

The loop works like this: first, the value of i is set to 3. Then, the while tests whether i is less than or equal to 10. This is the case when i equals 3, so the value of the i-th element of fib is set to the sum of the previous two values in the sequence. Then the i++ increments the value of i and the loop repeats. The loop terminates when i reaches 11.

A newline is not required between the condition and the body; but using one makes the program clearer unless the body is very simple.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.4 The do-until Statement

The do-until statement is similar to the while statement, except that it repeatedly executes a statement until a condition becomes true, and the test of the condition is at the end of the loop, so the body of the loop is always executed at least once. As with the condition in an if statement, the condition in a do-until statement is considered true if its value is non-zero, and false if its value is zero. If the value of the conditional expression in a do-until statement is a vector or a matrix, it is considered true only if it is non-empty and all of the elements are non-zero.

Octave’s do-until statement looks like this:

 
do
  body
until (condition)

Here body is a statement or list of statements that we call the body of the loop, and condition is an expression that controls how long the loop keeps running.

This example creates a variable fib that contains the first ten elements of the Fibonacci sequence.

 
fib = ones (1, 10);
i = 2;
do
  i++;
  fib (i) = fib (i-1) + fib (i-2);
until (i == 10)

A newline is not required between the do keyword and the body; but using one makes the program clearer unless the body is very simple.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.5 The for Statement

The for statement makes it more convenient to count iterations of a loop. The general form of the for statement looks like this:

 
for var = expression
  body
endfor

where body stands for any statement or list of statements, expression is any valid expression, and var may take several forms. Usually it is a simple variable name or an indexed variable. If the value of expression is a structure, var may also be a vector with two elements. See section Looping Over Structure Elements, below.

The assignment expression in the for statement works a bit differently than Octave’s normal assignment statement. Instead of assigning the complete result of the expression, it assigns each column of the expression to var in turn. If expression is a range, a row vector, or a scalar, the value of var will be a scalar each time the loop body is executed. If var is a column vector or a matrix, var will be a column vector each time the loop body is executed.

The following example shows another way to create a vector containing the first ten elements of the Fibonacci sequence, this time using the for statement:

 
fib = ones (1, 10);
for i = 3:10
  fib (i) = fib (i-1) + fib (i-2);
endfor

This code works by first evaluating the expression 3:10, to produce a range of values from 3 to 10 inclusive. Then the variable i is assigned the first element of the range and the body of the loop is executed once. When the end of the loop body is reached, the next value in the range is assigned to the variable i, and the loop body is executed again. This process continues until there are no more elements to assign.

Within Octave is it also possible to iterate over matrices or cell arrays using the for statement. For example consider

 
disp ("Loop over a matrix")
for i = [1,3;2,4]
  i
endfor
disp ("Loop over a cell array")
for i = {1,"two";"three",4}
  i
endfor

In this case the variable i takes on the value of the columns of the matrix or cell matrix. So the first loop iterates twice, producing two column vectors [1;2], followed by [3;4], and likewise for the loop over the cell array. This can be extended to loops over multi-dimensional arrays. For example:

 
a = [1,3;2,4]; c = cat (3, a, 2*a);
for i = c
  i
endfor

In the above case, the multi-dimensional matrix c is reshaped to a two-dimensional matrix as reshape (c, rows (c), prod (size (c)(2:end))) and then the same behavior as a loop over a two dimensional matrix is produced.

Although it is possible to rewrite all for loops as while loops, the Octave language has both statements because often a for loop is both less work to type and more natural to think of. Counting the number of iterations is very common in loops and it can be easier to think of this counting as part of looping rather than as something to do inside the loop.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.5.1 Looping Over Structure Elements

A special form of the for statement allows you to loop over all the elements of a structure:

 
for [ val, key ] = expression
  body
endfor

In this form of the for statement, the value of expression must be a structure. If it is, key and val are set to the name of the element and the corresponding value in turn, until there are no more elements. For example:

 
x.a = 1
x.b = [1, 2; 3, 4]
x.c = "string"
for [val, key] = x
  key
  val
endfor

     -| key = a
     -| val = 1
     -| key = b
     -| val =
     -| 
     -|   1  2
     -|   3  4
     -| 
     -| key = c
     -| val = string

The elements are not accessed in any particular order. If you need to cycle through the list in a particular way, you will have to use the function fieldnames and sort the list yourself.

The key variable may also be omitted. If it is, the brackets are also optional. This is useful for cycling through the values of all the structure elements when the names of the elements do not need to be known.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.6 The break Statement

The break statement jumps out of the innermost while, do-until, or for loop that encloses it. The break statement may only be used within the body of a loop. The following example finds the smallest divisor of a given integer, and also identifies prime numbers:

 
num = 103;
div = 2;
while (div*div <= num)
  if (rem (num, div) == 0)
    break;
  endif
  div++;
endwhile
if (rem (num, div) == 0)
  printf ("Smallest divisor of %d is %d\n", num, div)
else
  printf ("%d is prime\n", num);
endif

When the remainder is zero in the first while statement, Octave immediately breaks out of the loop. This means that Octave proceeds immediately to the statement following the loop and continues processing. (This is very different from the exit statement which stops the entire Octave program.)

Here is another program equivalent to the previous one. It illustrates how the condition of a while statement could just as well be replaced with a break inside an if:

 
num = 103;
div = 2;
while (1)
  if (rem (num, div) == 0)
    printf ("Smallest divisor of %d is %d\n", num, div);
    break;
  endif
  div++;
  if (div*div > num)
    printf ("%d is prime\n", num);
    break;
  endif
endwhile

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.7 The continue Statement

The continue statement, like break, is used only inside while, do-until, or for loops. It skips over the rest of the loop body, causing the next cycle around the loop to begin immediately. Contrast this with break, which jumps out of the loop altogether. Here is an example:

 
# print elements of a vector of random
# integers that are even.

# first, create a row vector of 10 random
# integers with values between 0 and 100:

vec = round (rand (1, 10) * 100);

# print what we're interested in:

for x = vec
  if (rem (x, 2) != 0)
    continue;
  endif
  printf ("%d\n", x);
endfor

If one of the elements of vec is an odd number, this example skips the print statement for that element, and continues back to the first statement in the loop.

This is not a practical example of the continue statement, but it should give you a clear understanding of how it works. Normally, one would probably write the loop like this:

 
for x = vec
  if (rem (x, 2) == 0)
    printf ("%d\n", x);
  endif
endfor

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.8 The unwind_protect Statement

Octave supports a limited form of exception handling modeled after the unwind-protect form of Lisp.

The general form of an unwind_protect block looks like this:

 
unwind_protect
  body
unwind_protect_cleanup
  cleanup
end_unwind_protect

where body and cleanup are both optional and may contain any Octave expressions or commands. The statements in cleanup are guaranteed to be executed regardless of how control exits body.

This is useful to protect temporary changes to global variables from possible errors. For example, the following code will always restore the original value of the global variable frobnosticate even if an error occurs in the first part of the unwind_protect block.

 
save_frobnosticate = frobnosticate;
unwind_protect
  frobnosticate = true;
  …
unwind_protect_cleanup
  frobnosticate = save_frobnosticate;
end_unwind_protect

Without unwind_protect, the value of frobnosticate would not be restored if an error occurs while evaluating the first part of the unwind_protect block because evaluation would stop at the point of the error and the statement to restore the value would not be executed.

In addition to unwind_protect, Octave supports another form of exception handling, the try block.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.9 The try Statement

The original form of a try block looks like this:

 
try
  body
catch
  cleanup
end_try_catch

where body and cleanup are both optional and may contain any Octave expressions or commands. The statements in cleanup are only executed if an error occurs in body.

No warnings or error messages are printed while body is executing. If an error does occur during the execution of body, cleanup can use the functions lasterr or lasterror to access the text of the message that would have been printed, as well as its identifier. The alternative form,

 
try
  body
catch err
  cleanup
end_try_catch

will automatically store the output of lasterror in the structure err. See section Errors and Warnings, for more information about the lasterr and lasterror functions.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

10.10 Continuation Lines

In the Octave language, most statements end with a newline character and you must tell Octave to ignore the newline character in order to continue a statement from one line to the next. Lines that end with the characters ... are joined with the following line before they are divided into tokens by Octave’s parser. For example, the lines

 
x = long_variable_name ...
    + longer_variable_name ...
    - 42

form a single statement.

Any text between the continuation marker and the newline character is ignored. For example, the statement

 
x = long_variable_name ...    # comment one
    + longer_variable_name ...comment two
    - 42                      # last comment

is equivalent to the one shown above.

Inside double-quoted string constants, the character \ has to be used as continuation marker. The \ must appear at the end of the line just before the newline character:

 
s = "This text starts in the first line \
and is continued in the second line."

Input that occurs inside parentheses can be continued to the next line without having to use a continuation marker. For example, it is possible to write statements like

 
if (fine_dining_destination == on_a_boat
    || fine_dining_destination == on_a_train)
  seuss (i, will, not, eat, them, sam, i, am, i,
         will, not, eat, green, eggs, and, ham);
endif

without having to add to the clutter with continuation markers.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11. Functions and Scripts

Complicated Octave programs can often be simplified by defining functions. Functions can be defined directly on the command line during interactive Octave sessions, or in external files, and can be called just like built-in functions.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.1 Introduction to Function and Script Files

There are seven different things covered in this section.

  1. Typing in a function at the command prompt.
  2. Storing a group of commands in a file — called a script file.
  3. Storing a function in a file—called a function file.
  4. Subfunctions in function files.
  5. Multiple functions in one script file.
  6. Private functions.
  7. Nested functions.

Both function files and script files end with an extension of .m, for MATLAB compatibility. If you want more than one independent functions in a file, it must be a script file (see section Script Files), and to use these functions you must execute the script file before you can use the functions that are in the script file.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.2 Defining Functions

In its simplest form, the definition of a function named name looks like this:

 
function name
  body
endfunction

A valid function name is like a valid variable name: a sequence of letters, digits and underscores, not starting with a digit. Functions share the same pool of names as variables.

The function body consists of Octave statements. It is the most important part of the definition, because it says what the function should actually do.

For example, here is a function that, when executed, will ring the bell on your terminal (assuming that it is possible to do so):

 
function wakeup
  printf ("\a");
endfunction

The printf statement (see section Input and Output) simply tells Octave to print the string "a". The special character ‘\a’ stands for the alert character (ASCII 7). See section Strings.

Once this function is defined, you can ask Octave to evaluate it by typing the name of the function.

Normally, you will want to pass some information to the functions you define. The syntax for passing parameters to a function in Octave is

 
function name (arg-list)
  body
endfunction

where arg-list is a comma-separated list of the function’s arguments. When the function is called, the argument names are used to hold the argument values given in the call. The list of arguments may be empty, in which case this form is equivalent to the one shown above.

To print a message along with ringing the bell, you might modify the wakeup to look like this:

 
function wakeup (message)
  printf ("\a%s\n", message);
endfunction

Calling this function using a statement like this

 
wakeup ("Rise and shine!");

will cause Octave to ring your terminal’s bell and print the message ‘Rise and shine!’, followed by a newline character (the ‘\n’ in the first argument to the printf statement).

In most cases, you will also want to get some information back from the functions you define. Here is the syntax for writing a function that returns a single value:

 
function ret-var = name (arg-list)
  body
endfunction

The symbol ret-var is the name of the variable that will hold the value to be returned by the function. This variable must be defined before the end of the function body in order for the function to return a value.

Variables used in the body of a function are local to the function. Variables named in arg-list and ret-var are also local to the function. See section Global Variables, for information about how to access global variables inside a function.

For example, here is a function that computes the average of the elements of a vector:

 
function retval = avg (v)
  retval = sum (v) / length (v);
endfunction

If we had written avg like this instead,

 
function retval = avg (v)
  if (isvector (v))
    retval = sum (v) / length (v);
  endif
endfunction

and then called the function with a matrix instead of a vector as the argument, Octave would have printed an error message like this:

 
error: value on right hand side of assignment is undefined

because the body of the if statement was never executed, and retval was never defined. To prevent obscure errors like this, it is a good idea to always make sure that the return variables will always have values, and to produce meaningful error messages when problems are encountered. For example, avg could have been written like this:

 
function retval = avg (v)
  retval = 0;
  if (isvector (v))
    retval = sum (v) / length (v);
  else
    error ("avg: expecting vector argument");
  endif
endfunction

There is still one additional problem with this function. What if it is called without an argument? Without additional error checking, Octave will probably print an error message that won’t really help you track down the source of the error. To allow you to catch errors like this, Octave provides each function with an automatic variable called nargin. Each time a function is called, nargin is automatically initialized to the number of arguments that have actually been passed to the function. For example, we might rewrite the avg function like this:

 
function retval = avg (v)
  retval = 0;
  if (nargin != 1)
    usage ("avg (vector)");
  endif
  if (isvector (v))
    retval = sum (v) / length (v);
  else
    error ("avg: expecting vector argument");
  endif
endfunction

Although Octave does not automatically report an error if you call a function with more arguments than expected, doing so probably indicates that something is wrong. Octave also does not automatically report an error if a function is called with too few arguments, but any attempt to use a variable that has not been given a value will result in an error. To avoid such problems and to provide useful messages, we check for both possibilities and issue our own error message.

Built-in Function: nargin ()
Built-in Function: nargin (fcn)

Within a function, return the number of arguments passed to the function. At the top level, return the number of command line arguments passed to Octave.

If called with the optional argument fcn—a function name or handle— return the declared number of arguments that the function can accept.

If the last argument to fcn is varargin the returned value is negative. For example, the function union for sets is declared as

 
function [y, ia, ib] = union (a, b, varargin)

and

nargin ("union")
⇒ -3

Programming Note: nargin does not work on built-in functions.

See also: nargout, varargin, isargout, varargout, nthargout.

Function File: inputname (n)

Return the name of the n-th argument to the calling function. If the argument is not a simple variable name, return an empty string.

Built-in Function: val = silent_functions ()
Built-in Function: old_val = silent_functions (new_val)
Built-in Function: silent_functions (new_val, "local")

Query or set the internal variable that controls whether internal output from a function is suppressed. If this option is disabled, Octave will display the results produced by evaluating expressions within a function body that are not terminated with a semicolon.

When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.3 Multiple Return Values

Unlike many other computer languages, Octave allows you to define functions that return more than one value. The syntax for defining functions that return multiple values is

 
function [ret-list] = name (arg-list)
  body
endfunction

where name, arg-list, and body have the same meaning as before, and ret-list is a comma-separated list of variable names that will hold the values returned from the function. The list of return values must have at least one element. If ret-list has only one element, this form of the function statement is equivalent to the form described in the previous section.

Here is an example of a function that returns two values, the maximum element of a vector and the index of its first occurrence in the vector.

 
function [max, idx] = vmax (v)
  idx = 1;
  max = v (idx);
  for i = 2:length (v)
    if (v (i) > max)
      max = v (i);
      idx = i;
    endif
  endfor
endfunction

In this particular case, the two values could have been returned as elements of a single array, but that is not always possible or convenient. The values to be returned may not have compatible dimensions, and it is often desirable to give the individual return values distinct names.

It is possible to use the nthargout function to obtain only some of the return values or several at once in a cell array. See section Cell Array Objects.

Function File: nthargout (n, func, …)
Function File: nthargout (n, ntot, func, …)

Return the nth output argument of function given by the function handle or string func. Any arguments after func are passed to func. The total number of arguments to call func with can be passed in ntot; by default ntot is n. The input n can also be a vector of indices of the output, in which case the output will be a cell array of the requested output arguments.

The intended use nthargout is to avoid intermediate variables. For example, when finding the indices of the maximum entry of a matrix, the following two compositions of nthargout

 
m = magic (5);
cell2mat (nthargout ([1, 2], @ind2sub, size (m),
                     nthargout (2, @max, m(:))))
⇒ 5   3

are completely equivalent to the following lines:

 
m = magic (5);
[~, idx] = max (M(:));
[i, j] = ind2sub (size (m), idx);
[i, j]
⇒ 5   3

It can also be helpful to have all output arguments in a single cell in the following manner:

 
USV = nthargout ([1:3], @svd, hilb (5));

See also: nargin, nargout, varargin, varargout, isargout.

In addition to setting nargin each time a function is called, Octave also automatically initializes nargout to the number of values that are expected to be returned. This allows you to write functions that behave differently depending on the number of values that the user of the function has requested. The implicit assignment to the built-in variable ans does not figure in the count of output arguments, so the value of nargout may be zero.

The svd and lu functions are examples of built-in functions that behave differently depending on the value of nargout.

It is possible to write functions that only set some return values. For example, calling the function

 
function [x, y, z] = f ()
  x = 1;
  z = 2;
endfunction

as

 
[a, b, c] = f ()

produces:

 
a = 1

b = [](0x0)

c = 2

along with a warning.

Built-in Function: nargout ()
Built-in Function: nargout (fcn)

Within a function, return the number of values the caller expects to receive. If called with the optional argument fcn—a function name or handle—return the number of declared output values that the function can produce. If the final output argument is varargout the returned value is negative.

For example,

 
f ()

will cause nargout to return 0 inside the function f and

 
[s, t] = f ()

will cause nargout to return 2 inside the function f.

In the second usage,

 
nargout (@histc) % or nargout ("histc")

will return 2, because histc has two outputs, whereas

 
nargout (@imread)

will return -2, because imread has two outputs and the second is varargout.

At the top level, nargout with no argument is undefined and will produce an error. nargout does not work for built-in functions and returns -1 for all anonymous functions.

See also: nargin, varargin, isargout, varargout, nthargout.

It is good practice at the head of a function to verify that it has been called correctly. In Octave the following idiom is seen frequently

 
if (nargin < min_#_inputs || nargin > max_#_inputs)
  print_usage ();
endif

which stops the function execution and prints a message about the correct way to call the function whenever the number of inputs is wrong.

For compatibility with MATLAB, nargchk, narginchk and nargoutchk are available which provide similar error checking.

Function File: msgstr = nargchk (minargs, maxargs, nargs)
Function File: msgstr = nargchk (minargs, maxargs, nargs, "string")
Function File: msgstruct = nargchk (minargs, maxargs, nargs, "struct")

Return an appropriate error message string (or structure) if the number of inputs requested is invalid.

This is useful for checking to see that the number of input arguments supplied to a function is within an acceptable range.

See also: nargoutchk, narginchk, error, nargin, nargout.

Function File: narginchk (minargs, maxargs)

Check for correct number of arguments or generate an error message if the number of arguments in the calling function is outside the range minargs and maxargs. Otherwise, do nothing.

Both minargs and maxargs need to be scalar numeric values. Zero, Inf and negative values are all allowed, and minargs and maxargs may be equal.

Note that this function evaluates nargin on the caller.

See also: nargchk, nargoutchk, error, nargout, nargin.

Function File: nargoutchk (minargs, maxargs)
Function File: msgstr = nargoutchk (minargs, maxargs, nargs)
Function File: msgstr = nargoutchk (minargs, maxargs, nargs, "string")
Function File: msgstruct = nargoutchk (minargs, maxargs, nargs, "struct")

Check for correct number of output arguments.

On the first form, returns an error unless the number of arguments in its caller is between the values of minargs and maxargs. It does nothing otherwise. Note that this function evaluates the value of nargout on the caller so its value must have not been tampered with.

Both minargs and maxargs need to be a numeric scalar. Zero, Inf and negative are all valid, and they can have the same value.

For backward compatibility reasons, the other forms return an appropriate error message string (or structure) if the number of outputs requested is invalid.

This is useful for checking to see that the number of output arguments supplied to a function is within an acceptable range.

See also: nargchk, narginchk, error, nargout, nargin.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.4 Variable-length Argument Lists

Sometimes the number of input arguments is not known when the function is defined. As an example think of a function that returns the smallest of all its input arguments. For example:

 
a = smallest (1, 2, 3);
b = smallest (1, 2, 3, 4);

In this example both a and b would be 1. One way to write the smallest function is

 
function val = smallest (arg1, arg2, arg3, arg4, arg5)
  body
endfunction

and then use the value of nargin to determine which of the input arguments should be considered. The problem with this approach is that it can only handle a limited number of input arguments.

If the special parameter name varargin appears at the end of a function parameter list it indicates that the function takes a variable number of input arguments. Using varargin the function looks like this

 
function val = smallest (varargin)
  body
endfunction

In the function body the input arguments can be accessed through the variable varargin. This variable is a cell array containing all the input arguments. See section Cell Arrays, for details on working with cell arrays. The smallest function can now be defined like this

 
function val = smallest (varargin)
  val = min ([varargin{:}]);
endfunction

This implementation handles any number of input arguments, but it’s also a very simple solution to the problem.

A slightly more complex example of varargin is a function print_arguments that prints all input arguments. Such a function can be defined like this

 
function print_arguments (varargin)
  for i = 1:length (varargin)
    printf ("Input argument %d: ", i);
    disp (varargin{i});
  endfor
endfunction

This function produces output like this

 
print_arguments (1, "two", 3);
     -| Input argument 1:  1
     -| Input argument 2: two
     -| Input argument 3:  3

Function File: [reg, prop] = parseparams (params)
Function File: [reg, var1, …] = parseparams (params, name1, default1, …)

Return in reg the cell elements of param up to the first string element and in prop all remaining elements beginning with the first string element. For example:

 
[reg, prop] = parseparams ({1, 2, "linewidth", 10})
reg =
{
  [1,1] = 1
  [1,2] = 2
}
prop =
{
  [1,1] = linewidth
  [1,2] = 10
}

The parseparams function may be used to separate regular numeric arguments from additional arguments given as property/value pairs of the varargin cell array.

In the second form of the call, available options are specified directly with their default values given as name-value pairs. If params do not form name-value pairs, or if an option occurs that does not match any of the available options, an error occurs. When called from an m-file function, the error is prefixed with the name of the caller function. The matching of options is case-insensitive.

See also: varargin.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.5 Ignoring Arguments

In the formal argument list, it is possible to use the dummy placeholder ~ instead of a name. This indicates that the corresponding argument value should be ignored and not stored to any variable.

 
function val = pick2nd (~, arg2)
  val = arg2;
endfunction

The value of nargin is not affected by using this declaration.

Return arguments can also be ignored using the same syntax. Functions may take advantage of ignored outputs to reduce the number of calculations performed. To do so, use the isargout function to query whether the output argument is wanted. For example:

 
function [out1, out2] = long_function (x, y, z)
  if (isargout (1))
    ## Long calculation
    …
    out1 = result;
  endif
  …
endfunction

Built-in Function: isargout (k)

Within a function, return a logical value indicating whether the argument k will be assigned to a variable on output. If the result is false, the argument has been ignored during the function call through the use of the tilde (~) special output argument. Functions can use isargout to avoid performing unnecessary calculations for outputs which are unwanted.

If k is outside the range 1:max (nargout), the function returns false. k can also be an array, in which case the function works element-by-element and a logical array is returned. At the top level, isargout returns an error.

See also: nargout, nargin, varargin, varargout, nthargout.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.6 Variable-length Return Lists

It is possible to return a variable number of output arguments from a function using a syntax that’s similar to the one used with the special varargin parameter name. To let a function return a variable number of output arguments the special output parameter name varargout is used. As with varargin, varargout is a cell array that will contain the requested output arguments.

As an example the following function sets the first output argument to 1, the second to 2, and so on.

 
function varargout = one_to_n ()
  for i = 1:nargout
    varargout{i} = i;
  endfor
endfunction

When called this function returns values like this

 
[a, b, c] = one_to_n ()
     ⇒ a =  1
     ⇒ b =  2
     ⇒ c =  3

If varargin (varargout) does not appear as the last element of the input (output) parameter list, then it is not special, and is handled the same as any other parameter name.

Function File: [r1, r2, …, rn] = deal (a)
Function File: [r1, r2, …, rn] = deal (a1, a2, …, an)

Copy the input parameters into the corresponding output parameters. If only one input parameter is supplied, its value is copied to each of the outputs.

For example,

 
[a, b, c] = deal (x, y, z);

is equivalent to

 
a = x;
b = y;
c = z;

and

 
[a, b, c] = deal (x);

is equivalent to

 
a = b = c = x;

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.7 Returning from a Function

The body of a user-defined function can contain a return statement. This statement returns control to the rest of the Octave program. It looks like this:

 
return

Unlike the return statement in C, Octave’s return statement cannot be used to return a value from a function. Instead, you must assign values to the list of return variables that are part of the function statement. The return statement simply makes it easier to exit a function from a deeply nested loop or conditional statement.

Here is an example of a function that checks to see if any elements of a vector are nonzero.

 
function retval = any_nonzero (v)
  retval = 0;
  for i = 1:length (v)
    if (v (i) != 0)
      retval = 1;
      return;
    endif
  endfor
  printf ("no nonzero elements found\n");
endfunction

Note that this function could not have been written using the break statement to exit the loop once a nonzero value is found without adding extra logic to avoid printing the message if the vector does contain a nonzero element.

Keyword: return

When Octave encounters the keyword return inside a function or script, it returns control to the caller immediately. At the top level, the return statement is ignored. A return statement is assumed at the end of every function definition.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.8 Default Arguments

Since Octave supports variable number of input arguments, it is very useful to assign default values to some input arguments. When an input argument is declared in the argument list it is possible to assign a default value to the argument like this

 
function name (arg1 = val1, …)
  body
endfunction

If no value is assigned to arg1 by the user, it will have the value val1.

As an example, the following function implements a variant of the classic “Hello, World” program.

 
function hello (who = "World")
  printf ("Hello, %s!\n", who);
endfunction

When called without an input argument the function prints the following

 
hello ();
     -| Hello, World!

and when it’s called with an input argument it prints the following

 
hello ("Beautiful World of Free Software");
     -| Hello, Beautiful World of Free Software!

Sometimes it is useful to explicitly tell Octave to use the default value of an input argument. This can be done writing a ‘:’ as the value of the input argument when calling the function.

 
hello (:);
     -| Hello, World!

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.9 Function Files

Except for simple one-shot programs, it is not practical to have to define all the functions you need each time you need them. Instead, you will normally want to save them in a file so that you can easily edit them, and save them for use at a later time.

Octave does not require you to load function definitions from files before using them. You simply need to put the function definitions in a place where Octave can find them.

When Octave encounters an identifier that is undefined, it first looks for variables or functions that are already compiled and currently listed in its symbol table. If it fails to find a definition there, it searches a list of directories (the path) for files ending in ‘.m’ that have the same base name as the undefined identifier.(5) Once Octave finds a file with a name that matches, the contents of the file are read. If it defines a single function, it is compiled and executed. See section Script Files, for more information about how you can define more than one function in a single file.

When Octave defines a function from a function file, it saves the full name of the file it read and the time stamp on the file. If the time stamp on the file changes, Octave may reload the file. When Octave is running interactively, time stamp checking normally happens at most once each time Octave prints the prompt. Searching for new function definitions also occurs if the current working directory changes.

Checking the time stamp allows you to edit the definition of a function while Octave is running, and automatically use the new function definition without having to restart your Octave session.

To avoid degrading performance unnecessarily by checking the time stamps on functions that are not likely to change, Octave assumes that function files in the directory tree ‘octave-home/share/octave/version/m’ will not change, so it doesn’t have to check their time stamps every time the functions defined in those files are used. This is normally a very good assumption and provides a significant improvement in performance for the function files that are distributed with Octave.

If you know that your own function files will not change while you are running Octave, you can improve performance by calling ignore_function_time_stamp ("all"), so that Octave will ignore the time stamps for all function files. Passing "system" to this function resets the default behavior.

Command: edit name
Command: edit field value
Command: value = edit get field

Edit the named function, or change editor settings.

If edit is called with the name of a file or function as its argument it will be opened in the text editor defined by EDITOR.

If edit is called with field and value variables, the value of the control field field will be set to value. If an output argument is requested and the first input argument is get then edit will return the value of the control field field. If the control field does not exist, edit will return a structure containing all fields and values. Thus, edit get all returns a complete control structure. The following control fields are used:

home

This is the location of user local m-files. Be sure it is in your path. The default is ‘~/octave’.

author

This is the name to put after the "## Author:" field of new functions. By default it guesses from the gecos field of the password database.

email

This is the e-mail address to list after the name in the author field. By default it guesses <$LOGNAME@$HOSTNAME>, and if $HOSTNAME is not defined it uses uname -n. You probably want to override this. Be sure to use the format <user@host>.

license
gpl

GNU General Public License (default).

bsd

BSD-style license without advertising clause.

pd

Public domain.

"text"

Your own default copyright and license.

Unless you specify ‘pd’, edit will prepend the copyright statement with "Copyright (C) yyyy Function Author".

mode

This value determines whether the editor should be started in async mode (editor is started in the background and Octave continues) or sync mode (Octave waits until the editor exits). Set it to "sync" to start the editor in sync mode. The default is "async" (see system).

editinplace

Determines whether files should be edited in place, without regard to whether they are modifiable or not. The default is false.

Built-in Function: mfilename ()
Built-in Function: mfilename ("fullpath")
Built-in Function: mfilename ("fullpathext")

Return the name of the currently executing file.

When called from outside an m-file return the empty string. Given the argument "fullpath", include the directory part of the file name, but not the extension. Given the argument "fullpathext", include the directory part of the file name and the extension.

Built-in Function: val = ignore_function_time_stamp ()
Built-in Function: old_val = ignore_function_time_stamp (new_val)

Query or set the internal variable that controls whether Octave checks the time stamp on files each time it looks up functions defined in function files. If the internal variable is set to "system", Octave will not automatically recompile function files in subdirectories of ‘octave-home/lib/version’ if they have changed since they were last compiled, but will recompile other function files in the search path if they change. If set to "all", Octave will not recompile any function files unless their definitions are removed with clear. If set to "none", Octave will always check time stamps on files to determine whether functions defined in function files need to recompiled.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.9.1 Manipulating the Load Path

When a function is called, Octave searches a list of directories for a file that contains the function declaration. This list of directories is known as the load path. By default the load path contains a list of directories distributed with Octave plus the current working directory. To see your current load path call the path function without any input or output arguments.

It is possible to add or remove directories to or from the load path using addpath and rmpath. As an example, the following code adds ‘~/Octave’ to the load path.

 
addpath ("~/Octave")

After this the directory ‘~/Octave’ will be searched for functions.

Built-in Function: addpath (dir1, …)
Built-in Function: addpath (dir1, …, option)

Add named directories to the function search path. If option is "-begin" or 0 (the default), prepend the directory name to the current path. If option is "-end" or 1, append the directory name to the current path. Directories added to the path must exist.

In addition to accepting individual directory arguments, lists of directory names separated by pathsep are also accepted. For example:

 
addpath ("dir1:/dir2:~/dir3")

See also: path, rmpath, genpath, pathdef, savepath, pathsep.

Built-in Function: genpath (dir)
Built-in Function: genpath (dir, skip, …)

Return a path constructed from dir and all its subdirectories. If additional string parameters are given, the resulting path will exclude directories with those names.

Built-in Function: rmpath (dir1, …)

Remove dir1, … from the current function search path.

In addition to accepting individual directory arguments, lists of directory names separated by pathsep are also accepted. For example:

 
rmpath ("dir1:/dir2:~/dir3")

See also: path, addpath, genpath, pathdef, savepath, pathsep.

Function File: savepath ()
Function File: savepath (file)
Function File: status = savepath (…)

Save the unique portion of the current function search path that is not set during Octave’s initialization process to file. If file is omitted, ‘~/.octaverc’ is used. If successful, savepath returns 0.

See also: path, addpath, rmpath, genpath, pathdef.

Built-in Function: path (…)

Modify or display Octave’s load path.

If nargin and nargout are zero, display the elements of Octave’s load path in an easy to read format.

If nargin is zero and nargout is greater than zero, return the current load path.

If nargin is greater than zero, concatenate the arguments, separating them with pathsep. Set the internal search path to the result and return it.

No checks are made for duplicate elements.

See also: addpath, rmpath, genpath, pathdef, savepath, pathsep.

Function File: val = pathdef ()

Return the default path for Octave. The path information is extracted from one of three sources. The possible sources, in order of preference, are:

  1. ~/.octaverc
  2. <octave-home>/…/<version>/m/startup/octaverc
  3. Octave’s path prior to changes by any octaverc.

See also: path, addpath, rmpath, genpath, savepath.

Built-in Function: val = pathsep ()
Built-in Function: old_val = pathsep (new_val)

Query or set the character used to separate directories in a path.

See also: filesep.

Built-in Function: rehash ()

Reinitialize Octave’s load path directory cache.

Built-in Function: file_in_loadpath (file)
Built-in Function: file_in_loadpath (file, "all")

Return the absolute name of file if it can be found in the list of directories specified by path. If no file is found, return an empty character string.

If the first argument is a cell array of strings, search each directory of the loadpath for element of the cell array and return the first that matches.

If the second optional argument "all" is supplied, return a cell array containing the list of all files that have the same name in the path. If no files are found, return an empty cell array.

See also: file_in_path, find_dir_in_path, path.

Built-in Function: restoredefaultpath (…)

Restore Octave’s path to its initial state at startup.

See also: path, addpath, rmpath, genpath, pathdef, savepath, pathsep.

Built-in Function: command_line_path (…)

Return the command line path variable.

See also: path, addpath, rmpath, genpath, pathdef, savepath, pathsep.

Built-in Function: find_dir_in_path (dir)
Built-in Function: find_dir_in_path (dir, "all")

Return the full name of the path element matching dir. The match is performed at the end of each path element. For example, if dir is "foo/bar", it matches the path element "/some/dir/foo/bar", but not "/some/dir/foo/bar/baz" "/some/dir/allfoo/bar".

The second argument is optional. If it is supplied, return a cell array containing all name matches rather than just the first.

See also: file_in_path, file_in_loadpath, path.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.9.2 Subfunctions

A function file may contain secondary functions called subfunctions. These secondary functions are only visible to the other functions in the same function file. For example, a file ‘f.m’ containing

 
function f ()
  printf ("in f, calling g\n");
  g ()
endfunction
function g ()
  printf ("in g, calling h\n");
  h ()
endfunction
function h ()
  printf ("in h\n")
endfunction

defines a main function f and two subfunctions. The subfunctions g and h may only be called from the main function f or from the other subfunctions, but not from outside the file ‘f.m’.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.9.3 Private Functions

In many cases one function needs to access one or more helper functions. If the helper function is limited to the scope of a single function, then subfunctions as discussed above might be used. However, if a single helper function is used by more than one function, then this is no longer possible. In this case the helper functions might be placed in a subdirectory, called "private", of the directory in which the functions needing access to this helper function are found.

As a simple example, consider a function func1, that calls a helper function func2 to do much of the work. For example:

 
function y = func1 (x)
  y = func2 (x);
endfunction

Then if the path to func1 is <directory>/func1.m, and if func2 is found in the directory <directory>/private/func2.m, then func2 is only available for use of the functions, like func1, that are found in <directory>.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.9.4 Nested Functions

Nested functions are similar to subfunctions in that only the main function is visible outside the file. However, they also allow for child functions to access the local variables in their parent function. This shared access mimics using a global variable to share information — but a global variable which is not visible to the rest of Octave. As a programming strategy, sharing data this way can create code which is difficult to maintain. It is recommended to use subfunctions in place of nested functions when possible.

As a simple example, consider a parent function foo, that calls a nested child function bar, with a shared variable x.

 
function y = foo ()
  x = 10;
  bar ();
  y = x;

  function bar ()
    x = 20;
  endfunction
endfunction

foo ()
 ⇒ 20

Notice that there is no special syntax for sharing x. This can lead to problems with accidental variable sharing between a parent function and its child. While normally variables are inherited, child function parameters and return values are local to the child function.

Now consider the function foobar that uses variables x and y. foobar calls a nested function foo which takes x as a parameter and returns y. foo then calls bat which does some computation.

 
function z = foobar ()
  x = 0;
  y = 0;
  z = foo (5);
  z += x + y;

  function y = foo (x)
    y = x + bat ();

    function z = bat ()
      z = x;
    endfunction
  endfunction
endfunction

foobar ()
    ⇒ 10

It is important to note that the x and y in foobar remain zero, as in foo they are a return value and parameter respectively. The x in bat refers to the x in foo.

Variable inheritance leads to a problem for eval and scripts. If a new variable is created in a parent function, it is not clear what should happen in nested child functions. For example, consider a parent function foo with a nested child function bar:

 
function y = foo (to_eval)
  bar ();
  eval (to_eval);

  function bar ()
    eval ("x = 100;");
    eval ("y = x;");
  endfunction
endfunction

foo ("x = 5;")
    ⇒ error: can not add variable "x" to a static workspace

foo ("y = 10;")
    ⇒ 10

foo ("")
    ⇒ 100

The parent function foo is unable to create a new variable x, but the child function bar was successful. Furthermore, even in an eval statement y in bar is the same y as in its parent function foo. The use of eval in conjunction with nested functions is best avoided.

As with subfunctions, only the first nested function in a file may be called from the outside. Inside a function the rules are more complicated. In general a nested function may call:

  1. Globally visible functions
  2. Any function that the nested function’s parent can call
  3. Sibling functions (functions that have the same parents)
  4. Direct children

As a complex example consider a parent function ex_top with two child functions, ex_a and ex_b. In addition, ex_a has two more child functions, ex_aa and ex_ab. For example:

 
function ex_top ()
  ## Can call: ex_top, ex_a, and ex_b
  ## Can NOT call: ex_aa and ex_ab

  function ex_a ()
    ## Call call everything

    function ex_aa ()
      ## Can call everything
    endfunction

    function ex_ab ()
      ## Can call everything
    endfunction
  endfunction

  function ex_b ()
    ## Can call: ex_top, ex_a, and ex_b
    ## Can NOT call: ex_aa and ex_ab
  endfunction
endfunction

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.9.5 Overloading and Autoloading

Functions can be overloaded to work with different input arguments. For example, the operator ’+’ has been overloaded in Octave to work with single, double, uint8, int32, and many other arguments. The preferred way to overload functions is through classes and object oriented programming (see section Function Overloading). Occasionally, however, one needs to undo user overloading and call the default function associated with a specific type. The builtin function exists for this purpose.

Built-in Function: […] = builtin (f, …)

Call the base function f even if f is overloaded to another function for the given type signature.

This is normally useful when doing object-oriented programming and there is a requirement to call one of Octave’s base functions rather than the overloaded one of a new class.

A trivial example which redefines the sin function to be the cos function shows how builtin works.

 
sin (0)
  ⇒ 0
function y = sin (x), y = cos (x); endfunction
sin (0)
  ⇒ 1
builtin ("sin", 0)
  ⇒ 0

A single dynamically linked file might define several functions. However, as Octave searches for functions based on the functions filename, Octave needs a manner in which to find each of the functions in the dynamically linked file. On operating systems that support symbolic links, it is possible to create a symbolic link to the original file for each of the functions which it contains.

However, there is at least one well known operating system that doesn’t support symbolic links. Making copies of the original file for each of the functions is undesirable as it increases the amount of disk space used by Octave. Instead Octave supplies the autoload function, that permits the user to define in which file a certain function will be found.

Built-in Function: autoload_map = autoload ()
Built-in Function: autoload (function, file)
Built-in Function: autoload (…, "remove")

Define function to autoload from file.

The second argument, file, should be an absolute file name or a file name in the same directory as the function or script from which the autoload command was run. file should not depend on the Octave load path.

Normally, calls to autoload appear in PKG_ADD script files that are evaluated when a directory is added to Octave’s load path. To avoid having to hardcode directory names in file, if file is in the same directory as the PKG_ADD script then

 
autoload ("foo", "bar.oct");

will load the function foo from the file bar.oct. The above usage when bar.oct is not in the same directory, or usages such as

 
autoload ("foo", file_in_loadpath ("bar.oct"))

are strongly discouraged, as their behavior may be unpredictable.

With no arguments, return a structure containing the current autoload map.

If a third argument "remove" is given, the function is cleared and not loaded anymore during the current Octave session.

See also: PKG_ADD.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.9.6 Function Locking

It is sometime desirable to lock a function into memory with the mlock function. This is typically used for dynamically linked functions in Oct-files or mex-files that contain some initialization, and it is desirable that calling clear does not remove this initialization.

As an example,

 
function my_function ()
  mlock ();
  …

prevents my_function from being removed from memory after it is called, even if clear is called. It is possible to determine if a function is locked into memory with the mislocked, and to unlock a function with munlock, which the following illustrates.

 
my_function ();
mislocked ("my_function")
⇒ ans = 1
munlock ("my_function");
mislocked ("my_function")
⇒ ans = 0

A common use of mlock is to prevent persistent variables from being removed from memory, as the following example shows:

 
function count_calls ()
  mlock ();
  persistent calls = 0;
  printf ("'count_calls' has been called %d times\n",
          ++calls);
endfunction

count_calls ();
-| 'count_calls' has been called 1 times

clear count_calls
count_calls ();
-| 'count_calls' has been called 2 times

mlock might equally be used to prevent changes to a function from having effect in Octave, though a similar effect can be had with the ignore_function_time_stamp function.

Built-in Function: mlock ()

Lock the current function into memory so that it can’t be cleared.

See also: munlock, mislocked, persistent.

Built-in Function: munlock ()
Built-in Function: munlock (fcn)

Unlock the named function fcn. If no function is named then unlock the current function.

See also: mlock, mislocked, persistent.

Built-in Function: mislocked ()
Built-in Function: mislocked (fcn)

Return true if the named function fcn is locked. If no function is named then return true if the current function is locked.

See also: mlock, munlock, persistent.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.9.7 Function Precedence

Given the numerous different ways that Octave can define a function, it is possible and even likely that multiple versions of a function, might be defined within a particular scope. The precedence of which function will be used within a particular scope is given by

  1. Subfunction A subfunction with the required function name in the given scope.
  2. Private function A function defined within a private directory of the directory which contains the current function.
  3. Class constructor A function that constuctors a user class as defined in chapter Object Oriented Programming.
  4. Class method An overloaded function of a class as in chapter Object Oriented Programming.
  5. Command-line Function A function that has been defined on the command-line.
  6. Autoload function A function that is marked as autoloaded with See autoload.
  7. A Function on the Path A function that can be found on the users load-path. There can also be Oct-file, mex-file or m-file versions of this function and the precedence between these versions are in that order.
  8. Built-in function A function that is a part of core Octave such as numel, size, etc.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.10 Script Files

A script file is a file containing (almost) any sequence of Octave commands. It is read and evaluated just as if you had typed each command at the Octave prompt, and provides a convenient way to perform a sequence of commands that do not logically belong inside a function.

Unlike a function file, a script file must not begin with the keyword function. If it does, Octave will assume that it is a function file, and that it defines a single function that should be evaluated as soon as it is defined.

A script file also differs from a function file in that the variables named in a script file are not local variables, but are in the same scope as the other variables that are visible on the command line.

Even though a script file may not begin with the function keyword, it is possible to define more than one function in a single script file and load (but not execute) all of them at once. To do this, the first token in the file (ignoring comments and other white space) must be something other than function. If you have no other statements to evaluate, you can use a statement that has no effect, like this:

 
# Prevent Octave from thinking that this
# is a function file:

1;

# Define function one:

function one ()
  …

To have Octave read and compile these functions into an internal form, you need to make sure that the file is in Octave’s load path (accessible through the path function), then simply type the base name of the file that contains the commands. (Octave uses the same rules to search for script files as it does to search for function files.)

If the first token in a file (ignoring comments) is function, Octave will compile the function and try to execute it, printing a message warning about any non-whitespace characters that appear after the function definition.

Note that Octave does not try to look up the definition of any identifier until it needs to evaluate it. This means that Octave will compile the following statements if they appear in a script file, or are typed at the command line,

 
# not a function file:
1;
function foo ()
  do_something ();
endfunction
function do_something ()
  do_something_else ();
endfunction

even though the function do_something is not defined before it is referenced in the function foo. This is not an error because Octave does not need to resolve all symbols that are referenced by a function until the function is actually evaluated.

Since Octave doesn’t look for definitions until they are needed, the following code will always print ‘bar = 3’ whether it is typed directly on the command line, read from a script file, or is part of a function body, even if there is a function or script file called ‘bar.m’ in Octave’s path.

 
eval ("bar = 3");
bar

Code like this appearing within a function body could fool Octave if definitions were resolved as the function was being compiled. It would be virtually impossible to make Octave clever enough to evaluate this code in a consistent fashion. The parser would have to be able to perform the call to eval at compile time, and that would be impossible unless all the references in the string to be evaluated could also be resolved, and requiring that would be too restrictive (the string might come from user input, or depend on things that are not known until the function is evaluated).

Although Octave normally executes commands from script files that have the name ‘file.m’, you can use the function source to execute commands from any file.

Built-in Function: source (file)

Parse and execute the contents of file.

This is equivalent to executing commands from a script file, but without requiring the file to be named ‘file.m’.

See also: run.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.11 Function Handles, Anonymous Functions, Inline Functions

It can be very convenient store a function in a variable so that it can be passed to a different function. For example, a function that performs numerical minimization needs access to the function that should be minimized.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.11.1 Function Handles

A function handle is a pointer to another function and is defined with the syntax

 
@function-name

For example,

 
f = @sin;

creates a function handle called f that refers to the function sin.

Function handles are used to call other functions indirectly, or to pass a function as an argument to another function like quad or fsolve. For example:

 
f = @sin;
quad (f, 0, pi)
    ⇒ 2

You may use feval to call a function using function handle, or simply write the name of the function handle followed by an argument list. If there are no arguments, you must use an empty argument list ‘()’. For example:

 
f = @sin;
feval (f, pi/4)
    ⇒ 0.70711
f (pi/4)
    ⇒ 0.70711

Built-in Function: is_function_handle (x)

Return true if x is a function handle.

See also: isa, typeinfo, class, functions.

Built-in Function: s = functions (fcn_handle)

Return a structure containing information about the function handle fcn_handle.

The structure s always contains these 3 fields:

function

The function name. For an anonymous function (no name) this will be the actual function definition.

type

Type of the function.

anonymous

The function is anonymous.

private

The function is private.

overloaded

The function overloads an existing function.

simple

The function is a built-in or m-file function.

subfunction

The function is a subfunction within an m-file.

file

The m-file that will be called to perform the function. This field is empty for anonymous and built-in functions.

In addition, some function types may return more information in additional fields.

Warning: functions is provided for debugging purposes only. It’s behavior may change in the future and programs should not depend on a particular output.

Built-in Function: func2str (fcn_handle)

Return a string containing the name of the function referenced by the function handle fcn_handle.

See also: str2func, functions.

Built-in Function: str2func (fcn_name)
Built-in Function: str2func (fcn_name, "global")

Return a function handle constructed from the string fcn_name. If the optional "global" argument is passed, locally visible functions are ignored in the lookup.

See also: func2str, inline.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.11.2 Anonymous Functions

Anonymous functions are defined using the syntax

 
@(argument-list) expression

Any variables that are not found in the argument list are inherited from the enclosing scope. Anonymous functions are useful for creating simple unnamed functions from expressions or for wrapping calls to other functions to adapt them for use by functions like quad. For example,

 
f = @(x) x.^2;
quad (f, 0, 10)
    ⇒ 333.33

creates a simple unnamed function from the expression x.^2 and passes it to quad,

 
quad (@(x) sin (x), 0, pi)
    ⇒ 2

wraps another function, and

 
a = 1;
b = 2;
quad (@(x) betainc (x, a, b), 0, 0.4)
    ⇒ 0.13867

adapts a function with several parameters to the form required by quad. In this example, the values of a and b that are passed to betainc are inherited from the current environment.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.11.3 Inline Functions

An inline function is created from a string containing the function body using the inline function. The following code defines the function f(x) = x^2 + 2.

 
f = inline ("x^2 + 2");

After this it is possible to evaluate f at any x by writing f(x).

Built-in Function: inline (str)
Built-in Function: inline (str, arg1, …)
Built-in Function: inline (str, n)

Create an inline function from the character string str.

If called with a single argument, the arguments of the generated function are extracted from the function itself. The generated function arguments will then be in alphabetical order. It should be noted that i, and j are ignored as arguments due to the ambiguity between their use as a variable or their use as an inbuilt constant. All arguments followed by a parenthesis are considered to be functions. If no arguments are found, a function taking a single argument named x will be created.

If the second and subsequent arguments are character strings, they are the names of the arguments of the function.

If the second argument is an integer n, the arguments are "x", "P1", …, "PN".

Programming Note: The use of inline is discouraged and it may be removed from a future version of Octave. The preferred way to create functions from strings is through the use of anonymous functions (see section Anonymous Functions) or str2func.

See also: argnames, formula, vectorize, str2func.

Built-in Function: argnames (fun)

Return a cell array of character strings containing the names of the arguments of the inline function fun.

See also: inline, formula, vectorize.

Built-in Function: formula (fun)

Return a character string representing the inline function fun. Note that char (fun) is equivalent to formula (fun).

See also: argnames, inline, vectorize.

Function File: symvar (s)

Identify the argument names in the function defined by a string. Common constant names such as pi, NaN, Inf, eps, i or j are ignored. The arguments that are found are returned in a cell array of strings. If no variables are found then the returned cell array is empty.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.12 Commands

Commands are a special class of functions that only accept string input arguments. A command can be called as an ordinary function, but it can also be called without the parentheses. For example,

 
my_command hello world

is equivalent to

 
my_command ("hello", "world")

The general form of a command call is

 
cmdname arg1 arg2

which translates directly to

 
cmdname ("arg1", "arg2", …)

Any regular function can be used as a command if it accepts string input arguments. For example:

 
toupper lower_case_arg
   ⇒ ans = LOWER_CASE_ARG

One difficulty of commands occurs when one of the string input arguments is stored in a variable. Because Octave can’t tell the difference between a variable name and an ordinary string, it is not possible to pass a variable as input to a command. In such a situation a command must be called as a function. For example:

 
strvar = "hello world";
toupper strvar
   ⇒ ans = STRVAR
toupper (strvar)
   ⇒ ans = HELLO WORLD

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.13 Organization of Functions Distributed with Octave

Many of Octave’s standard functions are distributed as function files. They are loosely organized by topic, in subdirectories of ‘octave-home/lib/octave/version/m’, to make it easier to find them.

The following is a list of all the function file subdirectories, and the types of functions you will find there.

audio

Functions for playing and recording sounds.

deprecated

Out-of-date functions which will eventually be removed from Octave.

elfun

Elementary functions, principally trigonometric.

@ftp

Class functions for the FTP object.

general

Miscellaneous matrix manipulations, like flipud, rot90, and triu, as well as other basic functions, like ismatrix, nargchk, etc.

geometry

Functions related to Delaunay triangulation.

help

Functions for Octave’s built-in help system.

image

Image processing tools. These functions require the X Window System.

io

Input-output functions.

linear-algebra

Functions for linear algebra.

miscellaneous

Functions that don’t really belong anywhere else.

optimization

Functions related to minimization, optimization, and root finding.

path

Functions to manage the directory path Octave uses to find functions.

pkg

Package manager for installing external packages of functions in Octave.

plot

Functions for displaying and printing two- and three-dimensional graphs.

polynomial

Functions for manipulating polynomials.

prefs

Functions implementing user-defined preferences.

set

Functions for creating and manipulating sets of unique values.

signal

Functions for signal processing applications.

sparse

Functions for handling sparse matrices.

specfun

Special functions such as bessel or factor.

special-matrix

Functions that create special matrix forms such as Hilbert or Vandermonde matrices.

startup

Octave’s system-wide startup file.

statistics

Statistical functions.

strings

Miscellaneous string-handling functions.

testfun

Functions for performing unit tests on other functions.

time

Functions related to time and date processing.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12. Errors and Warnings

Octave includes several functions for printing error and warning messages. When you write functions that need to take special action when they encounter abnormal conditions, you should print the error messages using the functions described in this chapter.

Since many of Octave’s functions use these functions, it is also useful to understand them, so that errors and warnings can be handled.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.1 Handling Errors

An error is something that occurs when a program is in a state where it doesn’t make sense to continue. An example is when a function is called with too few input arguments. In this situation the function should abort with an error message informing the user of the lacking input arguments.

Since an error can occur during the evaluation of a program, it is very convenient to be able to detect that an error occurred, so that the error can be fixed. This is possible with the try statement described in The try Statement.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.1.1 Raising Errors

The most common use of errors is for checking input arguments to functions. The following example calls the error function if the function f is called without any input arguments.

 
function f (arg1)
  if (nargin == 0)
    error ("not enough input arguments");
  endif
endfunction

When the error function is called, it prints the given message and returns to the Octave prompt. This means that no code following a call to error will be executed.

Built-in Function: error (template, …)
Built-in Function: error (id, template, …)

Format the optional arguments under the control of the template string template using the same rules as the printf family of functions (see section Formatted Output) and print the resulting message on the stderr stream. The message is prefixed by the character string ‘error: ’.

Calling error also sets Octave’s internal error state such that control will return to the top level without evaluating any more commands. This is useful for aborting from functions or scripts.

If the error message does not end with a new line character, Octave will print a traceback of all the function calls leading to the error. For example, given the following function definitions:

 
function f () g (); end
function g () h (); end
function h () nargin == 1 || error ("nargin != 1"); end

calling the function f will result in a list of messages that can help you to quickly locate the exact location of the error:

 
f ()
error: nargin != 1
error: called from:
error:   error at line -1, column -1
error:   h at line 1, column 27
error:   g at line 1, column 15
error:   f at line 1, column 15

If the error message ends in a new line character, Octave will print the message but will not display any traceback messages as it returns control to the top level. For example, modifying the error message in the previous example to end in a new line causes Octave to only print a single message:

 
function h () nargin == 1 || error ("nargin != 1\n"); end
f ()
error: nargin != 1

A null string ("") input to error will be ignored and the code will continue running as if the statement were a NOP. This is for compatibility with MATLAB. It also makes it possible to write code such as

 
err_msg = "";
if (CONDITION 1)
  err_msg = "CONDITION 1 found";
elseif (CONDITION2)
  err_msg = "CONDITION 2 found";
…
endif
error (err_msg);

which will only stop execution if an error has been found.

Implementation Note: For compatibility with MATLAB, escape sequences (e.g., "n" => newline) are processed in template regardless of whether template has been defined within single quotes as long as there are two or more input arguments. Use a second backslash to stop interpolation of the escape sequence (e.g., "\\n") or use the regexptranslate function.

See also: warning, lasterror.

Since it is common to use errors when there is something wrong with the input to a function, Octave supports functions to simplify such code. When the print_usage function is called, it reads the help text of the function calling print_usage, and presents a useful error. If the help text is written in Texinfo it is possible to present an error message that only contains the function prototypes as described by the @deftypefn parts of the help text. When the help text isn’t written in Texinfo, the error message contains the entire help message.

Consider the following function.

 
## -*- texinfo -*-
## @deftypefn {Function File} f (@var{arg1})
## Function help text goes here…
## @end deftypefn
function f (arg1)
  if (nargin == 0)
    print_usage ();
  endif
endfunction

When it is called with no input arguments it produces the following error.

 
f ()

-|  error: Invalid call to f.  Correct usage is:
-|  
-|   -- Function File: f (ARG1)
-|  
-|  
-|  Additional help for built-in functions and operators is
-|  available in the online version of the manual.  Use the command
-|  `doc <topic>' to search the manual index.
-|  
-|  Help and information about Octave is also available on the WWW
-|  at http://www.octave.org and via the help@octave.org
-|  mailing list.

Function File: print_usage ()
Function File: print_usage (name)

Print the usage message for a function. When called with no input arguments the print_usage function displays the usage message of the currently executing function.

See also: help.

Built-in Function: usage (msg)

Print the message msg, prefixed by the string ‘usage: ’, and set Octave’s internal error state such that control will return to the top level without evaluating any more commands. This is useful for aborting from functions.

After usage is evaluated, Octave will print a traceback of all the function calls leading to the usage message.

You should use this function for reporting problems errors that result from an improper call to a function, such as calling a function with an incorrect number of arguments, or with arguments of the wrong type. For example, most functions distributed with Octave begin with code like this

 
if (nargin != 2)
  usage ("foo (a, b)");
endif

to check for the proper number of arguments.

Function File: beep ()

Produce a beep from the speaker (or visual bell).

See also: puts, fputs, printf, fprintf.

Built-in Function: val = beep_on_error ()
Built-in Function: old_val = beep_on_error (new_val)
Built-in Function: beep_on_error (new_val, "local")

Query or set the internal variable that controls whether Octave will try to ring the terminal bell before printing an error message.

When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.1.2 Catching Errors

When an error occurs, it can be detected and handled using the try statement as described in The try Statement. As an example, the following piece of code counts the number of errors that occurs during a for loop.

 
number_of_errors = 0;
for n = 1:100
  try
    …
  catch
    number_of_errors++;
  end_try_catch
endfor

The above example treats all errors the same. In many situations it can however be necessary to discriminate between errors, and take different actions depending on the error. The lasterror function returns a structure containing information about the last error that occurred. As an example, the code above could be changed to count the number of errors related to the ‘*’ operator.

 
number_of_errors = 0;
for n = 1:100
  try
    …
  catch
    msg = lasterror.message;
    if (strfind (msg, "operator *"))
      number_of_errors++;
    endif
  end_try_catch
endfor

Alternatively, the output of the lasterror function can be found in a variable indicated immediately after the catch keyword, as in the example below showing how to redirect an error as a warning:

 
try
  …
catch err
  warning(err.identifier, err.message);
  …
end_try_catch

Built-in Function: lasterr = lasterror ()
Built-in Function: lasterror (err)
Built-in Function: lasterror ("reset")

Query or set the last error message structure. When called without arguments, return a structure containing the last error message and other information related to this error. The elements of the structure are:

message

The text of the last error message

identifier

The message identifier of this error message

stack

A structure containing information on where the message occurred. This may be an empty structure if the information cannot be obtained. The fields of the structure are:

file

The name of the file where the error occurred

name

The name of function in which the error occurred

line

The line number at which the error occurred

column

An optional field with the column number at which the error occurred

The last error structure may be set by passing a scalar structure, err, as input. Any fields of err that match those above are set while any unspecified fields are initialized with default values.

If lasterror is called with the argument "reset", all fields are set to their default values.

See also: lasterr, error, lastwarn.

Built-in Function: [msg, msgid] = lasterr ()
Built-in Function: lasterr (msg)
Built-in Function: lasterr (msg, msgid)

Query or set the last error message. When called without input arguments, return the last error message and message identifier. With one argument, set the last error message to msg. With two arguments, also set the last message identifier.

See also: lasterror, error, lastwarn.

It is also possible to assign an identification string to an error. If an error has such an ID the user can catch this error as will be shown in the next example. To assign an ID to an error, simply call error with two string arguments, where the first is the identification string, and the second is the actual error. Note that error IDs are in the format "NAMESPACE:ERROR-NAME". The namespace "Octave" is used for Octave’s own errors. Any other string is available as a namespace for user’s own errors.

The next example counts indexing errors. The errors are caught using the field identifier of the structure returned by the function lasterror.

 
number_of_errors = 0;
for n = 1:100
  try
    …
  catch
    id = lasterror.identifier;
    if (strcmp (id, "Octave:invalid-indexing"))
      number_of_errors++;
    endif
  end_try_catch
endfor

The functions distributed with Octave can issue one of the following errors.

Octave:invalid-context

Indicates the error was generated by an operation that cannot be executed in the scope from which it was called. For example, the function print_usage () when called from the Octave prompt raises this error.

Octave:invalid-input-arg

Indicates that a function was called with invalid input arguments.

Octave:invalid-fun-call

Indicates that a function was called in an incorrect way, e.g., wrong number of input arguments.

Octave:invalid-indexing

Indicates that a data-type was indexed incorrectly, e.g., real-value index for arrays, non-existent field of a structure.

Octave:bad-alloc

Indicates that memory couldn’t be allocated.

Octave:undefined-function

Indicates a call to a function that is not defined. The function may exist but Octave is unable to find it in the search path.

When an error has been handled it is possible to raise it again. This can be useful when an error needs to be detected, but the program should still abort. This is possible using the rethrow function. The previous example can now be changed to count the number of errors related to the ‘*’ operator, but still abort if another kind of error occurs.

 
number_of_errors = 0;
for n = 1:100
  try
    …
  catch
    msg = lasterror.message;
    if (strfind (msg, "operator *"))
      number_of_errors++;
    else
      rethrow (lasterror);
    endif
  end_try_catch
endfor

Built-in Function: rethrow (err)

Reissue a previous error as defined by err. err is a structure that must contain at least the "message" and "identifier" fields. err can also contain a field "stack" that gives information on the assumed location of the error. Typically err is returned from lasterror.

See also: lasterror, lasterr, error.

Built-in Function: err = errno ()
Built-in Function: err = errno (val)
Built-in Function: err = errno (name)

Return the current value of the system-dependent variable errno, set its value to val and return the previous value, or return the named error code given name as a character string, or -1 if name is not found.

Built-in Function: errno_list ()

Return a structure containing the system-dependent errno values.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.1.3 Recovering From Errors

Octave provides several ways of recovering from errors. There are try/catch blocks, unwind_protect/unwind_protect_cleanup blocks, and finally the onCleanup command.

The onCleanup command associates an ordinary Octave variable (the trigger) with an arbitrary function (the action). Whenever the Octave variable ceases to exist—whether due to a function return, an error, or simply because the variable has been removed with clear—then the assigned function is executed.

The function can do anything necessary for cleanup such as closing open file handles, printing an error message, or restoring global variables to their initial values. The last example is a very convenient idiom for Octave code. For example:

 
function rand42
  old_state = rand ("state");
  restore_state = onCleanup (@() rand ("state", old_state);
  rand ("state", 42);
  …
endfunction  # rand generator state restored by onCleanup

Built-in Function: obj = onCleanup (function)

Create a special object that executes a given function upon destruction. If the object is copied to multiple variables (or cell or struct array elements) or returned from a function, function will be executed after clearing the last copy of the object. Note that if multiple local onCleanup variables are created, the order in which they are called is unspecified. For similar functionality See section The unwind_protect Statement.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.2 Handling Warnings

Like an error, a warning is issued when something unexpected happens. Unlike an error, a warning doesn’t abort the currently running program. A simple example of a warning is when a number is divided by zero. In this case Octave will issue a warning and assign the value Inf to the result.

 
a = 1/0
     -| warning: division by zero
     ⇒ a = Inf

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.2.1 Issuing Warnings

It is possible to issue warnings from any code using the warning function. In its most simple form, the warning function takes a string describing the warning as its input argument. As an example, the following code controls if the variable ‘a’ is non-negative, and if not issues a warning and sets ‘a’ to zero.

 
a = -1;
if (a < 0)
  warning ("'a' must be non-negative.  Setting 'a' to zero.");
  a = 0;
endif
     -| 'a' must be non-negative.  Setting 'a' to zero.

Since warnings aren’t fatal to a running program, it is not possible to catch a warning using the try statement or something similar. It is however possible to access the last warning as a string using the lastwarn function.

It is also possible to assign an identification string to a warning. If a warning has such an ID the user can enable and disable this warning as will be described in the next section. To assign an ID to a warning, simply call warning with two string arguments, where the first is the identification string, and the second is the actual warning. Note that warning IDs are in the format "NAMESPACE:WARNING-NAME". The namespace "Octave" is used for Octave’s own warnings. Any other string is available as a namespace for user’s own warnings.

Built-in Function: warning (template, …)
Built-in Function: warning (id, template, …)
Built-in Function: warning ("on", id)
Built-in Function: warning ("off", id)
Built-in Function: warning ("query", id)
Built-in Function: warning ("error", id)
Built-in Function: warning (state, id, "local")

Format the optional arguments under the control of the template string template using the same rules as the printf family of functions (see section Formatted Output) and print the resulting message on the stderr stream. The message is prefixed by the character string ‘warning: ’. You should use this function when you want to notify the user of an unusual condition, but only when it makes sense for your program to go on.

The optional message identifier allows users to enable or disable warnings tagged by id. A message identifier is of the form "NAMESPACE:WARNING-NAME". Octave’s own warnings use the "Octave" namespace (see XREFwarning_ids). The special identifier "all" may be used to set the state of all warnings.

If the first argument is "on" or "off", set the state of a particular warning using the identifier id. If the first argument is "query", query the state of this warning instead. If the identifier is omitted, a value of "all" is assumed. If you set the state of a warning to "error", the warning named by id is handled as if it were an error instead. So, for example, the following handles all warnings as errors:

 
warning ("error");

If the state is "on", "off", or "error" and the third argument is "local", then the warning state will be set temporarily, until the end of the current function. Changes to warning states that are set locally affect the current function and all functions called from the current scope. The previous warning state is restored on return from the current function. The "local" option is ignored if used in the top-level workspace.

Implementation Note: For compatibility with MATLAB, escape sequences (e.g., "n" => newline) are processed in template regardless of whether template has been defined within single quotes as long as there are two or more input arguments. Use a second backslash to stop interpolation of the escape sequence (e.g., "\\n") or use the regexptranslate function.

See also: warning_ids, lastwarn, error.

Built-in Function: [msg, msgid] = lastwarn ()
Built-in Function: lastwarn (msg)
Built-in Function: lastwarn (msg, msgid)

Query or set the last warning message. When called without input arguments, return the last warning message and message identifier. With one argument, set the last warning message to msg. With two arguments, also set the last message identifier.

See also: warning, lasterror, lasterr.

The functions distributed with Octave can issue one of the following warnings.

Octave:abbreviated-property-match

By default, the Octave:abbreviated-property-match warning is enabled.

Octave:array-to-scalar

If the Octave:array-to-scalar warning is enabled, Octave will warn when an implicit conversion from an array to a scalar value is attempted. By default, the Octave:array-to-scalar warning is disabled.

Octave:array-to-vector

If the Octave:array-to-vector warning is enabled, Octave will warn when an implicit conversion from an array to a vector value is attempted. By default, the Octave:array-to-vector warning is disabled.

Octave:assign-as-truth-value

If the Octave:assign-as-truth-value warning is enabled, a warning is issued for statements like

 
if (s = t)
  …

since such statements are not common, and it is likely that the intent was to write

 
if (s == t)
  …

instead.

There are times when it is useful to write code that contains assignments within the condition of a while or if statement. For example, statements like

 
while (c = getc ())
  …

are common in C programming.

It is possible to avoid all warnings about such statements by disabling the Octave:assign-as-truth-value warning, but that may also let real errors like

 
if (x = 1)  # intended to test (x == 1)!
  …

slip by.

In such cases, it is possible suppress errors for specific statements by writing them with an extra set of parentheses. For example, writing the previous example as

 
while ((c = getc ()))
  …

will prevent the warning from being printed for this statement, while allowing Octave to warn about other assignments used in conditional contexts.

By default, the Octave:assign-as-truth-value warning is enabled.

Octave:associativity-change

If the Octave:associativity-change warning is enabled, Octave will warn about possible changes in the meaning of some code due to changes in associativity for some operators. Associativity changes have typically been made for MATLAB compatibility. By default, the Octave:associativity-change warning is enabled.

Octave:autoload-relative-file-name

If the Octave:autoload-relative-file-name is enabled, Octave will warn when parsing autoload() function calls with relative paths to function files. This usually happens when using autoload() calls in PKG_ADD files, when the PKG_ADD file is not in the same directory as the .oct file referred to by the autoload() command. By default, the Octave:autoload-relative-file-name warning is enabled.

Octave:broadcast

Warn when performing broadcasting operations. By default, this is enabled. See Broadcasting in the chapter Vectorization and Faster Code Execution of the manual.

Octave:built-in-variable-assignment

By default, the Octave:built-in-variable-assignment warning is enabled.

Octave:deprecated-keyword

If the Octave:deprecated-keyword warning is enabled, a warning is issued when Octave encounters a keyword that is obsolete and scheduled for removal from Octave. By default, the Octave:deprecated-keyword warning is enabled.

Octave:divide-by-zero

If the Octave:divide-by-zero warning is enabled, a warning is issued when Octave encounters a division by zero. By default, the Octave:divide-by-zero warning is enabled.

Octave:fopen-file-in-path

By default, the Octave:fopen-file-in-path warning is enabled.

Octave:function-name-clash

If the Octave:function-name-clash warning is enabled, a warning is issued when Octave finds that the name of a function defined in a function file differs from the name of the file. (If the names disagree, the name declared inside the file is ignored.) By default, the Octave:function-name-clash warning is enabled.

Octave:future-time-stamp

If the Octave:future-time-stamp warning is enabled, Octave will print a warning if it finds a function file with a time stamp that is in the future. By default, the Octave:future-time-stamp warning is enabled.

Octave:glyph-render

By default, the Octave:glyph-render warning is enabled.

Octave:imag-to-real

If the Octave:imag-to-real warning is enabled, a warning is printed for implicit conversions of complex numbers to real numbers. By default, the Octave:imag-to-real warning is disabled.

Octave:load-file-in-path

By default, the Octave:load-file-in-path warning is enabled.

Octave:logical-conversion

By default, the Octave:logical-conversion warning is enabled.

Octave:matlab-incompatible

Print warnings for Octave language features that may cause compatibility problems with MATLAB. By default, the Octave:matlab-incompatible warning is disabled. The –traditional or –braindead startup options for Octave may also be of use, see section Command Line Options.

Octave:md5sum-file-in-path

By default, the Octave:md5sum-file-in-path warning is enabled.

Octave:missing-glyph

By default, the Octave:missing-glyph warning is enabled.

Octave:missing-semicolon

If the Octave:missing-semicolon warning is enabled, Octave will warn when statements in function definitions don’t end in semicolons. By default the Octave:missing-semicolon warning is disabled.

Octave:mixed-string-concat

If the Octave:mixed-string-concat warning is enabled, print a warning when concatenating a mixture of double and single quoted strings. By default, the Octave:mixed-string-concat warning is disabled.

Octave:neg-dim-as-zero

If the Octave:neg-dim-as-zero warning is enabled, print a warning for expressions like

 
eye (-1)

By default, the Octave:neg-dim-as-zero warning is disabled.

Octave:nested-functions-coerced

By default, the Octave:nested-functions-coerced warning is enabled.

Octave:noninteger-range-as-index

By default, the Octave:noninteger-range-as-index warning is enabled.

Octave:num-to-str

If the Octave:num-to-str warning is enable, a warning is printed for implicit conversions of numbers to their ASCII character equivalents when strings are constructed using a mixture of strings and numbers in matrix notation. For example,

 
[ "f", 111, 111 ]
⇒ "foo"

elicits a warning if the Octave:num-to-str warning is enabled. By default, the Octave:num-to-str warning is enabled.

Octave:possible-matlab-short-circuit-operator

If the Octave:possible-matlab-short-circuit-operator warning is enabled, Octave will warn about using the not short circuiting operators & and | inside if or while conditions. They normally never short circuit, but MATLAB always short circuits if any logical operators are used in a condition. You can turn on the option

 
do_braindead_shortcircuit_evaluation (1)

if you would like to enable this short-circuit evaluation in Octave. Note that the && and || operators always short circuit in both Octave and MATLAB, so it’s only necessary to enable MATLAB-style short-circuiting if it’s too arduous to modify existing code that relies on this behavior. By default, the Octave:possible-matlab-short-circuit-operator warning is enabled.

Octave:precedence-change

If the Octave:precedence-change warning is enabled, Octave will warn about possible changes in the meaning of some code due to changes in precedence for some operators. Precedence changes have typically been made for MATLAB compatibility. By default, the Octave:precedence-change warning is enabled.

Octave:recursive-path-search

By default, the Octave:recursive-path-search warning is enabled.

Octave:remove-init-dir

The path function changes the search path that Octave uses to find functions. It is possible to set the path to a value which excludes Octave’s own built-in functions. If the Octave:remove-init-dir warning is enabled then Octave will warn when the path function has been used in a way that may render Octave unworkable. By default, the Octave:remove-init-dir warning is enabled.

Octave:reload-forces-clear

If several functions have been loaded from the same file, Octave must clear all the functions before any one of them can be reloaded. If the Octave:reload-forces-clear warning is enabled, Octave will warn you when this happens, and print a list of the additional functions that it is forced to clear. By default, the Octave:reload-forces-clear warning is enabled.

Octave:resize-on-range-error

If the Octave:resize-on-range-error warning is enabled, print a warning when a matrix is resized by an indexed assignment with indices outside the current bounds. By default, the ## Octave:resize-on-range-error warning is disabled.

Octave:separator-insert

Print warning if commas or semicolons might be inserted automatically in literal matrices. By default, the Octave:separator-insert warning is disabled.

Octave:shadowed-function

By default, the Octave:shadowed-function warning is enabled.

Octave:single-quote-string

Print warning if a single quote character is used to introduce a string constant. By default, the Octave:single-quote-string warning is disabled.

Octave:singular-matrix-div

By default, the Octave:singular-matrix-div warning is enabled.

Octave:sqrtm:SingularMatrix

By default, the Octave:sqrtm:SingularMatrix warning is enabled.

Octave:str-to-num

If the Octave:str-to-num warning is enabled, a warning is printed for implicit conversions of strings to their numeric ASCII equivalents. For example,

 
"abc" + 0
⇒ 97 98 99

elicits a warning if the Octave:str-to-num warning is enabled. By default, the Octave:str-to-num warning is disabled.

Octave:undefined-return-values

If the Octave:undefined-return-values warning is disabled, print a warning if a function does not define all the values in the return list which are expected. By default, the Octave:undefined-return-values warning is enabled.

Octave:variable-switch-label

If the Octave:variable-switch-label warning is enabled, Octave will print a warning if a switch label is not a constant or constant expression. By default, the Octave:variable-switch-label warning is disabled.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

12.2.2 Enabling and Disabling Warnings

The warning function also allows you to control which warnings are actually printed to the screen. If the warning function is called with a string argument that is either "on" or "off" all warnings will be enabled or disabled.

It is also possible to enable and disable individual warnings through their string identifications. The following code will issue a warning

 
warning ("example:non-negative-variable", 
         "'a' must be non-negative.  Setting 'a' to zero.");

while the following won’t issue a warning

 
warning ("off", "example:non-negative-variable");
warning ("example:non-negative-variable", 
         "'a' must be non-negative.  Setting 'a' to zero.");

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13. Debugging

Octave includes a built-in debugger to aid in the development of scripts. This can be used to interrupt the execution of an Octave script at a certain point, or when certain conditions are met. Once execution has stopped, and debug mode is entered, the symbol table at the point where execution has stopped can be examined and modified to check for errors.

The normal command-line editing and history functions are available in debug mode.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13.1 Entering Debug Mode

There are two basic means of interrupting the execution of an Octave script. These are breakpoints (see section Breakpoints), discussed in the next section, and interruption based on some condition.

Octave supports three means to stop execution based on the values set in the functions debug_on_interrupt, debug_on_warning, and debug_on_error.

Built-in Function: val = debug_on_interrupt ()
Built-in Function: old_val = debug_on_interrupt (new_val)
Built-in Function: debug_on_interrupt (new_val, "local")

Query or set the internal variable that controls whether Octave will try to enter debugging mode when it receives an interrupt signal (typically generated with C-c). If a second interrupt signal is received before reaching the debugging mode, a normal interrupt will occur.

When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.

See also: debug_on_error, debug_on_warning.

Built-in Function: val = debug_on_warning ()
Built-in Function: old_val = debug_on_warning (new_val)
Built-in Function: debug_on_warning (new_val, "local")

Query or set the internal variable that controls whether Octave will try to enter the debugger when a warning is encountered.

When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.

See also: debug_on_error, debug_on_interrupt.

Built-in Function: val = debug_on_error ()
Built-in Function: old_val = debug_on_error (new_val)
Built-in Function: debug_on_error (new_val, "local")

Query or set the internal variable that controls whether Octave will try to enter the debugger when an error is encountered. This will also inhibit printing of the normal traceback message (you will only see the top-level error message).

When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.

See also: debug_on_warning, debug_on_interrupt.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13.2 Leaving Debug Mode

Use either dbcont or return to leave the debug mode and continue the normal execution of the script.

Command: dbcont

Leave command-line debugging mode and continue code execution normally.

See also: dbstep, dbquit.

To quit debug mode and return directly to the prompt without executing any additional code use dbquit.

Command: dbquit

Quit debugging mode immediately without further code execution and return to the Octave prompt.

See also: dbcont, dbstep.

Finally, typing exit or quit at the debug prompt will result in Octave terminating normally.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13.3 Breakpoints

Breakpoints can be set in any m-file function by using the dbstop function.

Built-in Function: rline = dbstop ("func")
Built-in Function: rline = dbstop ("func", line)
Built-in Function: rline = dbstop ("func", line1, line2, …)

Set a breakpoint in function func.

Arguments are

func

Function name as a string variable. When already in debug mode this should be left out and only the line should be given.

line

Line number where the breakpoint should be set. Multiple lines may be given as separate arguments or as a vector.

When called with a single argument func, the breakpoint is set at the first executable line in the named function.

The optional output rline is the real line number where the breakpoint was set. This can differ from specified line if the line is not executable. For example, if a breakpoint attempted on a blank line then Octave will set the real breakpoint at the next executable line.

See also: dbclear, dbstatus, dbstep, debug_on_error, debug_on_warning, debug_on_interrupt.

Breakpoints in class methods are also supported (e.g., dbstop ("@class/method")). However, breakpoints cannot be set in built-in functions (e.g., sin, etc.) or dynamically loaded functions (i.e., oct-files).

To set a breakpoint immediately upon entering a function use line number 1, or omit the line number entirely and just give the function name. When setting the breakpoint Octave will ignore the leading comment block, and the breakpoint will be set on the first executable statement in the function. For example:

 
dbstop ("asind", 1)
⇒ 29

Note that the return value of 29 means that the breakpoint was effectively set to line 29. The status of breakpoints in a function can be queried with dbstatus.

Built-in Function: dbstatus ()
Built-in Function: brk_list = dbstatus ()
Built-in Function: brk_list = dbstatus ("func")

Report the location of active breakpoints.

When called with no input or output arguments, print the list of all functions with breakpoints and the line numbers where those breakpoints are set. If a function name func is specified then only report breakpoints for the named function.

The optional return argument brk_list is a struct array with the following fields.

name

The name of the function with a breakpoint.

file

The name of the m-file where the function code is located.

line

A line number, or vector of line numbers, with a breakpoint.

See also: dbclear, dbwhere.

Reusing the previous example, dbstatus ("asind") will return 29. The breakpoints listed can then be cleared with the dbclear function.

Built-in Function: dbclear ("func")
Built-in Function: dbclear ("func", line, …)
Built-in Function: dbclear (line, …)

Delete a breakpoint in the function func.

Arguments are

func

Function name as a string variable. When already in debug mode this argument should be omitted and only the line number should be given.

line

Line number from which to remove a breakpoint. Multiple lines may be given as separate arguments or as a vector.

When called without a line number specification all breakpoints in the named function are cleared.

If the requested line is not a breakpoint no action is performed.

See also: dbstop, dbstatus, dbwhere.

A breakpoint may also be set in a subfunction. For example, if a file contains the functions

 
function y = func1 (x)
  y = func2 (x);
endfunction
function y = func2 (x)
  y = x + 1;
endfunction

then a breakpoint can be set at the start of the subfunction directly with

 
dbstop (["func1", filemarker(), "func2"])
⇒ 5

Note that filemarker returns the character that marks subfunctions from the file containing them. Unless the default has been changed this character is ‘>’. Thus, a quicker and more normal way to set the breakpoint would be

 
dbstop func1>func2

Another simple way of setting a breakpoint in an Octave script is the use of the keyboard function.

Built-in Function: keyboard ()
Built-in Function: keyboard ("prompt")

This function is normally used for simple debugging. When the keyboard function is executed, Octave prints a prompt and waits for user input. The input strings are then evaluated and the results are printed. This makes it possible to examine the values of variables within a function, and to assign new values if necessary. To leave the prompt and return to normal execution type ‘return’ or ‘dbcont’. The keyboard function does not return an exit status.

If keyboard is invoked without arguments, a default prompt of ‘debug> ’ is used.

See also: dbstop, dbcont, dbquit.

The keyboard function is placed in a script at the point where the user desires that the execution be stopped. It automatically sets the running script into the debug mode.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13.4 Debug Mode

There are three additional support functions that allow the user to find out where in the execution of a script Octave entered the debug mode, and to print the code in the script surrounding the point where Octave entered debug mode.

Command: dbwhere

In debugging mode, report the current file and line number where execution is stopped.

See also: dbstatus, dbcont, dbstep, dbup.

Command: dbtype
Command: dbtype lineno
Command: dbtype startl:endl
Command: dbtype startl:end
Command: dbtype func
Command: dbtype func lineno
Command: dbtype func startl:endl
Command: dbtype func startl:end

Display a script file with line numbers.

When called with no arguments in debugging mode, display the script file currently being debugged. An optional range specification can be used to list only a portion of the file. The special keyword "end" is a valid line number specification for the last line of the file.

When called with the name of a function, list that script file with line numbers.

See also: dbwhere, dbstatus, dbstop.

Command: dblist
Command: dblist n

In debugging mode, list n lines of the function being debugged centered around the current line to be executed. If unspecified n defaults to 10 (+/- 5 lines)

See also: dbwhere, dbtype.

You may also use isdebugmode to determine whether the debugger is currently active.

Built-in Function: isdebugmode ()

Return true if in debugging mode, otherwise false.

See also: dbwhere, dbstack, dbstatus.

Debug mode also allows single line stepping through a function using the command dbstep.

Command: dbstep
Command: dbstep n
Command: dbstep in
Command: dbstep out
Command: dbnext

In debugging mode, execute the next n lines of code. If n is omitted, execute the next single line of code. If the next line of code is itself defined in terms of an m-file remain in the existing function.

Using dbstep in will cause execution of the next line to step into any m-files defined on the next line. Using dbstep out will cause execution to continue until the current function returns.

dbnext is an alias for dbstep.

See also: dbcont, dbquit.

When in debug mode the <RETURN> key will execute the last entered command. This is useful, for example, after hitting a breakpoint and entering dbstep once. After that, one can advance line by line through the code with only a single key stroke.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13.5 Call Stack

The function being debugged may be the leaf node of a series of function calls. After examining values in the current subroutine it may turn out that the problem occurred in earlier pieces of code. Use dbup and dbdown to move up and down through the series of function calls to locate where variables first took on the wrong values. dbstack shows the entire series of function calls and at what level debugging is currently taking place.

Command: dbstack
Command: dbstack n
Command: dbstack -completenames
Built-in Function: [stack, idx] = dbstack (…)

Display or return current debugging function stack information. With optional argument n, omit the n innermost stack frames.

Although accepted, the argument -completenames is silently ignored. Octave always returns absolute file names. The arguments n and -completenames can be both specified in any order.

The optional return argument stack is a struct array with the following fields:

file

The name of the m-file where the function code is located.

name

The name of the function with a breakpoint.

line

The line number of an active breakpoint.

column

The column number of the line where the breakpoint begins.

scope

Undocumented.

context

Undocumented.

The return argument idx specifies which element of the stack struct array is currently active.

See also: dbup, dbdown, dbwhere, dbstatus.

Built-in Function: dbup
Built-in Function: dbup (n)

In debugging mode, move up the execution stack n frames. If n is omitted, move up one frame.

See also: dbstack, dbdown.

Built-in Function: dbdown
Built-in Function: dbdown (n)

In debugging mode, move down the execution stack n frames. If n is omitted, move down one frame.

See also: dbstack, dbup.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13.6 Profiling

Octave supports profiling of code execution on a per-function level. If profiling is enabled, each call to a function (supporting built-ins, operators, functions in oct- and mex-files, user-defined functions in Octave code and anonymous functions) is recorded while running Octave code. After that, this data can aid in analyzing the code behavior, and is in particular helpful for finding “hot spots” in the code which use up a lot of computation time and are the best targets to spend optimization efforts on.

The main command for profiling is profile, which can be used to start or stop the profiler and also to query collected data afterwards. The data is returned in an Octave data structure which can then be examined or further processed by other routines or tools.

Command: profile on
Command: profile off
Command: profile resume
Command: profile clear
Function File: S = profile ("status")
Function File: T = profile ("info")

Control the built-in profiler.

profile on

Start the profiler, clearing all previously collected data if there is any.

profile off

Stop profiling. The collected data can later be retrieved and examined with calls like S = profile ("info").

profile clear

Clear all collected profiler data.

profile resume

Restart profiling without cleaning up the old data and instead all newly collected statistics are added to the already existing ones.

S = profile ("status")

Return a structure filled with certain information about the current status of the profiler. At the moment, the only field is ProfilerStatus which is either "on" or "off".

T = profile ("info")

Return the collected profiling statistics in the structure T. The flat profile is returned in the field FunctionTable which is an array of structures, each entry corresponding to a function which was called and for which profiling statistics are present. Furthermore, the field Hierarchical contains the hierarchical call-tree. Each node has an index into the FunctionTable identifying the function it corresponds to as well as data fields for number of calls and time spent at this level in the call-tree.

See also: profshow, profexplore.

An easy way to get an overview over the collected data is profshow. This function takes the profiler data returned by profile as input and prints a flat profile, for instance:

 
 Function Attr     Time (s)        Calls
----------------------------------------
   >myfib    R        2.195        13529
binary <=             0.061        13529
 binary -             0.050        13528
 binary +             0.026         6764

This shows that most of the run time was spent executing the function ‘myfib’, and some minor proportion evaluating the listed binary operators. Furthermore, it is shown how often the function was called and the profiler also records that it is recursive.

Function File: profshow (data)
Function File: profshow (data, n)

Show flat profiler results.

This command prints out profiler data as a flat profile. data is the structure returned by profile ("info"). If n is given, it specifies the number of functions to show in the profile; functions are sorted in descending order by total time spent in them. If there are more than n included in the profile, those will not be shown. n defaults to 20.

The attribute column shows ‘R’ for recursive functions and nothing otherwise.

See also: profexplore, profile.

Function File: profexplore ()
Function File: profexplore (data)

Interactively explore hierarchical profiler output.

Assuming data is the structure with profile data returned by profile ("info"), this command opens an interactive prompt that can be used to explore the call-tree. Type help to get a list of possible commands. If data is omitted, profile ("info") is called and used in its place.

See also: profile, profshow.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13.7 Profiler Example

Below, we will give a short example of a profiler session. See section Profiling, for the documentation of the profiler functions in detail. Consider the code:

 
global N A;

N = 300;
A = rand (N, N);

function xt = timesteps (steps, x0, expM)
  global N;

  if (steps == 0)
    xt = NA (N, 0);
  else
    xt = NA (N, steps);
    x1 = expM * x0;
    xt(:, 1) = x1;
    xt(:, 2 : end) = timesteps (steps - 1, x1, expM);
  endif
endfunction

function foo ()
  global N A;

  initial = @(x) sin (x);
  x0 = (initial (linspace (0, 2 * pi, N)))';

  expA = expm (A);
  xt = timesteps (100, x0, expA);
endfunction

function fib = bar (N)
  if (N <= 2)
    fib = 1;
  else
    fib = bar (N - 1) + bar (N - 2);
  endif
endfunction

If we execute the two main functions, we get:

 
tic; foo; toc;
⇒ Elapsed time is 2.37338 seconds.

tic; bar (20); toc;
⇒ Elapsed time is 2.04952 seconds.

But this does not give much information about where this time is spent; for instance, whether the single call to expm is more expensive or the recursive time-stepping itself. To get a more detailed picture, we can use the profiler.

 
profile on;
foo;
profile off;

data = profile ("info");
profshow (data, 10);

This prints a table like:

 
   #  Function Attr     Time (s)        Calls
---------------------------------------------
   7      expm             1.034            1
   3  binary *             0.823          117
  41  binary \             0.188            1
  38  binary ^             0.126            2
  43 timesteps    R        0.111          101
  44        NA             0.029          101
  39  binary +             0.024            8
  34      norm             0.011            1
  40  binary -             0.004          101
  33   balance             0.003            1

The entries are the individual functions which have been executed (only the 10 most important ones), together with some information for each of them. The entries like ‘binary *’ denote operators, while other entries are ordinary functions. They include both built-ins like expm and our own routines (for instance timesteps). From this profile, we can immediately deduce that expm uses up the largest proportion of the processing time, even though it is only called once. The second expensive operation is the matrix-vector product in the routine timesteps. (6)

Timing, however, is not the only information available from the profile. The attribute column shows us that timesteps calls itself recursively. This may not be that remarkable in this example (since it’s clear anyway), but could be helpful in a more complex setting. As to the question of why is there a ‘binary \’ in the output, we can easily shed some light on that too. Note that data is a structure array (Structure Arrays) which contains the field FunctionTable. This stores the raw data for the profile shown. The number in the first column of the table gives the index under which the shown function can be found there. Looking up data.FunctionTable(41) gives:

 
  scalar structure containing the fields:

    FunctionName = binary \
    TotalTime =  0.18765
    NumCalls =  1
    IsRecursive = 0
    Parents =  7
    Children = [](1x0)

Here we see the information from the table again, but have additional fields Parents and Children. Those are both arrays, which contain the indices of functions which have directly called the function in question (which is entry 7, expm, in this case) or been called by it (no functions). Hence, the backslash operator has been used internally by expm.

Now let’s take a look at bar. For this, we start a fresh profiling session (profile on does this; the old data is removed before the profiler is restarted):

 
profile on;
bar (20);
profile off;

profshow (profile ("info"));

This gives:

 
   #            Function Attr     Time (s)        Calls
-------------------------------------------------------
   1                 bar    R        2.091        13529
   2           binary <=             0.062        13529
   3            binary -             0.042        13528
   4            binary +             0.023         6764
   5             profile             0.000            1
   8               false             0.000            1
   6              nargin             0.000            1
   7           binary !=             0.000            1
   9 __profiler_enable__             0.000            1

Unsurprisingly, bar is also recursive. It has been called 13,529 times in the course of recursively calculating the Fibonacci number in a suboptimal way, and most of the time was spent in bar itself.

Finally, let’s say we want to profile the execution of both foo and bar together. Since we already have the run-time data collected for bar, we can restart the profiler without clearing the existing data and collect the missing statistics about foo. This is done by:

 
profile resume;
foo;
profile off;

profshow (profile ("info"), 10);

As you can see in the table below, now we have both profiles mixed together.

 
   #  Function Attr     Time (s)        Calls
---------------------------------------------
   1       bar    R        2.091        13529
  16      expm             1.122            1
  12  binary *             0.798          117
  46  binary \             0.185            1
  45  binary ^             0.124            2
  48 timesteps    R        0.115          101
   2 binary <=             0.062        13529
   3  binary -             0.045        13629
   4  binary +             0.041         6772
  49        NA             0.036          101

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

14. Input and Output

Octave supports several ways of reading and writing data to or from the prompt or a file. The simplest functions for data Input and Output (I/O) are easy to use, but only provide limited control of how data is processed. For more control, a set of functions modeled after the C standard library are also provided by Octave.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]