.. meta::
   :keywords: web2py, framework, DAL, データベース抽象化レイヤ, Row class, Rowクラス



.. currentmodule:: dal

.. _class_row: 

Row
===

Rowはレコードのクラスです。 :ref:`class_rows` がレコードセットですから、Rowはレコード行になります。

参考： :ref:`Set Rows Row クラスについて<set_rows_row>`


.. include:: class_diagrams/row.html

インスタンス化
--------------

Rowsクラスはイテレータを装備しており、Rowsインスタンスから要素を抜き出すとRowインスタンスとなります [#f1]_ 。

この他、Tableクラスの :ref:`class_table_shortcut` から直接、Rowインスタンスを生成することも可能です。しかしこの方法は、
内部でRowsインスタンスを生成して要素を切り出しています。つまり単なるショットカット機能です。

.. topic:: 【 Rowインスタンスの生成 】

	* 生成・・・・・・Rowsクラスから要素を抜き出します。
		:: 

			>>> rows = db(db.person).select()
			>>> row = rows[0]		# personテーブルの先頭レコード

			>>> row = db.person[1]		# personテーブルの先頭レコード

			>>> row = db.person(1)		# personテーブルの先頭レコード


メソッド
--------


メソッド説明用サンプルでは次のテーブルを利用します。

	 :: 

		db.define_table('person',
		    Field('name'),
		    Field('birthday', 'datetime')

.. method:: Row.as_dict([, datetime_to_str ]) -> 辞書型

	Rowインスタンスを辞書型データに変換します。同様のメソッドとして、Rowsクラスの :meth:`~dal.Rows.as_dict` メソッド
	があります。

	:: 

		>>> print db.person(1).as_dict()
		{'name': 'Totoceco', 'id': 1, 'birthday': datetime.date(2008, 12, 23)}

	datetime_to_str
		日付時間フィールドの文字列変換の制御を行います。デフォルトはFalseです。

		:: 

			>>> print db.person(1).as_dict(datetime_to_str=True)
			{'name': 'Totoceco', 'id': 1, 'birthday': '2008-12-23 00:00:00'}

.. _class_row_function: 

組み込み関数
------------

Rowインスタンスには、特殊な無名関数（lambda）が含まれています。Rowインスタンスの生成時、正確にはSetクラスの :meth:`~dal.Set.select` 
メソッドが動作する時にRowインスタンスに埋め込まれます。

この関数はメソッドではありません。しかし辞書型データの特徴をうまく利用して、メソッドのように動作します。

.. function:: Row.update_record

	Rowインスタンスのデータと共に、データベース上のデータも更新します。

	:: 

		>>> row = db.person(1)
		>>> row.update_record(name='Socepopa')

	Rowインスタンスのデータをステップ・バイ・ステップで修正し、データベースに一度で反映させることも可能です。

	:: 

		>>> row = db.person(1)
		>>> row.name = 'Socepopa'
		>>> row.birthday = datetime.datetime(2008, 12, 23, 0, 0)
		>>> row.update_record()

	この場合、update_record のパラメータは指定しません。

	Rowクラスにはupdateメソッドがありますが、これはPythonの辞書型でもともと用意しているメソッドです。

		:: 

			>>> row.update(name='Socepopa')

		当然ですが、このメソッドはRowインスタンスのデータは変更しても、データベース上のデータは変更できません。


	.. note:: 

		update_record が動作するのは、:meth:`~Set.select` にidフィールドが含まれており、cacheableオプションが
		True でない場合です。


	参考： `update_record <http://web2py.com/book/default/chapter/06?search=instantiate#update_record>`_ ｜ `update_record（日本語） <http://www.web2py.com/books/default/chapter/33/06#update_record>`_ 


.. function:: Row.delete_record() -> 削除レコード数

	Rowインスタンスの、主キー値と一致するデータベースのレコードを削除します。戻り値は削除レコード数です。

	:: 

		>>> row.delete_record()
		1

	delete_record はRowもしくはRowsインスタンスの該当レコードデータは削除しません。このため必要に応じて、データベースから
	読み直すなどの処理が必要です。


----

.. [#f1] Pythonのinstance型オブジェクトではありませんが、簡単に説明するために **インスタンス** という言葉を使用しています。