.. highlight:: rest

:mod:`tabular.tab`
=======================

.. automodule:: tabular.tab

.. autoclass:: tabular.tab.tabarray
	:members:
	:show-inheritance:
	
	.. automethod:: __new__
	.. automethod:: __array_finalize__
	.. automethod:: __getitem__
	.. automethod:: __getslice__
	

	.. method:: copy()
	
		Return a copy of the tabarray.
		
		.. note:: 

			This method is actually automatically inherited from 
			the NumPy ndarray, but is explicitly included here to 
			emphasize its utility.  This documentation is modified 
			from NumPy's.

		**Notes**
		
			This is like:
		
			>>> tb.tabarray(array=a, dtype=a.dtype, copy=True)
		
		**Examples**
		
			Create an array x, with a reference y and a copy z:
		
			>>> x = tb.tabarray(records=[(1,2,3),(4,5,6)])	
			>>> y = x
			>>> z = x.copy()
		
			Note that, when we modify x, y changes, but not z:
			
			>>> x[0] = (0,0,0)
			>>> x[0] == y[0]
			True
			>>> x[0] == z[0]
			False


	.. method:: tolist()

		Return the array as a possibly nested list.

		Return a copy of the array data as a (nested) Python list.
		Data items are converted to the nearest compatible Python type.
		
		.. note::
		
			This method is actually automatically inherited from 
			the NumPy ndarray, but is explicitly included here to 
			emphasize its utility.  This documentation is modified 
			from NumPy's.		

		**Returns**
		
			**y** : list

				The possibly nested list of array elements.

		**Notes**
		
			The array may be recreated, ``a = tb.tabarray(records=a.tolist())``.

		**Examples**
		
			>>> a = tb.tabarray(records=[('a', 2), ('c', 1)])
			>>> list(a)
			[('a', 2), ('c', 1)]
			>>> type(list(a)[0])
			<class 'numpy.core.records.record'>
			>>> a.tolist()
			[('a', 2), ('c', 1)]
			>>> atype(a.tolist()[0])
			<type 'tuple'>


	.. method:: sort(kind='quicksort', order=None)
	
		Sort an array, in-place.
		
		.. note:: 

			This method is actually automatically inherited from 
			the NumPy ndarray, but is explicitly included here to 
			emphasize its utility.  This documentation is modified 
			from NumPy's. 
		
		**Parameters**
	
			**kind** : {'quicksort', 'mergesort', 'heapsort'}, optional
			
				Sorting algorithm. Default is 'quicksort'.
		
			**order** : string or list, optional
		
				This argument specifies which fields to compare first, 
				second, and so on.  This can be a string corresponding
				to a single column name, or a list of column names.
				This list does not need to include all of the column names.
	
		**See Also**
			
			numpy.sort : Return a sorted copy of an array.
			argsort : Indirect sort.			
			lexsort : Indirect stable sort on multiple keys.
			searchsorted : Find elements in sorted array.
		
		**Notes**
	
			See ``numpy.sort`` for notes on the different sorting algorithms.
		
		**Examples**
			
			Use the `order` keyword to specify a column name (or list 
			of columns) to use:
		
			>>> a = tabarray(records=[('a', 2), ('c', 1)], names=['x', 'y'])
			>>> a.sort(order='y')
			>>> a
			tabarray([('c', 1), ('a', 2)],
				  dtype=[('x', '|S1'), ('y', '<i4')])


	.. method:: repeat(repeats)
	
		Repeat elements of a tabarray.

		.. note:: 

			This method is actually automatically inherited from 
			the NumPy ndarray, but is explicitly included here to 
			emphasize its utility.  This documentation is modified 
			from NumPy's. 
	
		**Parameters**

			**repeats** : {int, array of ints}
	
				The number of repetitions for each element.  `repeats` is broadcasted
				to fit the number of records.

		**Returns**
		
			**repeated_array** : tabarray
		
				Output array which has the same number of columns as 
				the origial tabarray.

		**See Also**

			numpy.repeat :  function called by this method
	
		**Examples**
	
			>>> x = tb.tabarray(records=[(1,2),(3,4)])
			>>> x.repeat(2)
			tabarray([(1, 2), (1, 2), (3, 4), (3, 4)], 
				  dtype=[('f0', '<i4'), ('f1', '<i4')])
			>>> x.repeat([1, 2])
			tabarray([(1, 2), (3, 4), (3, 4)], 
				  dtype=[('f0', '<i4'), ('f1', '<i4')])


	.. method:: put(ind, v, mode='raise')

		Changes specific elements of one array by replacing from another array.

		.. note:: 

			This method is actually automatically inherited from 
			the NumPy ndarray, but is explicitly included here to 
			emphasize its utility.  This documentation is modified 
			from NumPy's. 
		
		The indexing works on the flattened target array, `put` is roughly
		equivalent to::
		
			for i, val in zip(ind, v):
				x.flat[i] = val
		
		**Parameters**
		
		**ind** : array_like
		
			Target indices, interpreted as integers.
		
		**v** : array_like
		
			Values to place in the original array at target indices. 
			If `v` is shorter than `ind` it will be repeated as necessary.
		
		**mode** : {'raise', 'wrap', 'clip'}, optional
		
			Specifies how out-of-bounds indices will behave.
			
			*	'raise' -- raise an error (default)
			*	'wrap' -- wrap around
			*	'clip' -- clip to the range
			
			'clip' mode means that all indices that are too large are replaced
			by the index that addresses the last element along that axis. Note
			that this disables indexing with negative numbers.
			
		**See Also**

			putmask, place
		
		**Examples**

			>>> x = tb.tabarray(columns=[range(5)])
			>>> y = tb.tabarray(columns=[range(10,15)])
			>>> x.put([0, 2], y)
			>>> x
			tabarray([(10,), (1,), (11,), (3,), (4,)], 
			      dtype=[('f0', '<i4')])

			>>> x = tb.tabarray(columns=[range(5)])
			>>> y = tb.tabarray(columns=[range(10,15)])
			>>> x.put(22, y, mode='clip')
			>>> x
			tabarray([(0,), (1,), (2,), (3,), (10,)], 			
				  dtype=[('f0', '<i4')])
