dok/utility.dok

======  Torch utility functions ======
{{anchor:torch.utility.dok}}

This functions are used in all Torch package for creating and handling classes.
The most interesting function is probably [[#torch.class|torch.class()]] which allows
the user to create easily new classes. [[#torch.typename|torch.typename()]] might
also be interesting to check what is the class of a given Torch object.

The other functions are more for advanced users.

====  [metatable] torch.class(name, [parentName]) ====
{{anchor:torch.class}}

Creates a new ''Torch'' class called ''name''. If ''parentName'' is provided, the class will inherit
''parentName'' methods. A class is a table which has a particular metatable.

If ''name'' is of the form ''package.className'' then the class ''className'' will be added to the specified ''package''.
In that case, ''package'' has to be a valid (and already loaded) package. If ''name'' does not contain any ''"."'',
then the class will be defined in the global environment.

One [or two] (meta)tables are returned. These tables contain all the method
provided by the class [and its parent class if it has been provided]. After
a call to ''torch.class()'' you have to fill-up properly the metatable.

After the class definition is complete, constructing a new class //name// will be achieved by a call to ''//name//()''.
This call will first call the method <file lua>__init()</file> if it exists, passing all arguments of ''//name//()''.

<file lua>
 require "torch"

 -- for naming convenience
 do
   --- creates a class "Foo"
   local Foo = torch.class('Foo')
 
   --- the initializer
   function Foo:__init()
     self.contents = "this is some text"
   end

   --- a method
   function Foo:print()
     print(self.contents)
   end

   --- another one
   function Foo:bip()
     print('bip')
   end

 end

 --- now create an instance of Foo
 foo = Foo()

 --- try it out
 foo:print()

 --- create a class torch.Bar which
 --- inherits from Foo
 do
   local Bar, parent = torch.class('torch.Bar', 'Foo')

   --- the initializer
   function Bar:__init(stuff)
     --- call the parent initializer on ourself
     parent.__init(self)
 
     --- do some stuff
     self.stuff = stuff
   end

   --- a new method
   function Bar:boing()
     print('boing!')
   end

   --- override parent's method
   function Bar:print()
     print(self.contents)
     print(self.stuff)
   end
 end

 --- create a new instance and use it
 bar = torch.Bar("ha ha!")
 bar:print() -- overrided method
 bar:boing() -- child method
 bar:bip()   -- parent's method

</file>

For advanced users, it is worth mentionning that ''torch.class()'' actually
calls [[#torch.newmetatable|torch.newmetatable()]].  with a particular
constructor. The constructor creates a Lua table and set the right
metatable on it, and then calls <file lua>__init()</file> if it exists in the
metatable. It also sets a [[#torch.factory|factory]] field <file lua>__factory</file> such that it
is possible to create an empty object of this class.

====  [string] torch.typename(object) ====
{{anchor:torch.typename}}

Checks if ''object'' has a metatable. If it does, and if it corresponds to a
''Torch'' class, then returns a string containing the name of the
class. Returns ''nil'' in any other cases.

A Torch class is a class created with [[#torch.class|torch.class()]] or
[[#torch.newmetatable|torch.newmetatable()]].

==== [userdata] torch.typename2id(string) ====
{{anchor:torch.typename2id}}

Given a Torch class name specified by ''string'', returns a unique
corresponding id (defined by a ''lightuserdata'' pointing on the internal
structure of the class). This might be useful to do a //fast// check of the
class of an object (if used with [[#torch.id|torch.id()]]), avoiding string
comparisons.

Returns ''nil'' if ''string'' does not specify a Torch object.

==== [userdata] torch.id(object) ====
{{anchor:torch.id}}

Returns a unique id corresponding to the //class// of the given Torch object.
The id is defined by a ''lightuserdata'' pointing on the internal structure
of the class.

Returns ''nil'' if ''object'' is not a Torch object.

This is different from the //object// id returned by [[#torch.pointer|torch.pointer()]].

====  [table] torch.newmetatable(name, parentName, constructor) ====
{{anchor:torch.newmetatable}}

Register a new metatable as a Torch type with the given string ''name''. The new metatable is returned.

If the string ''parentName'' is not ''nil'' and is a valid Torch type (previously created
by ''torch.newmetatable()'') then set the corresponding metatable as a metatable to the returned new
metatable. 

If the given ''constructor'' function is not ''nil'', then assign to the variable ''name'' the given constructor.
The given ''name'' might be of the form ''package.className'', in which case the ''className'' will be local to the
specified ''package''. In that case, ''package'' must be a valid and already loaded package.

====  [function] torch.factory(name) ====
{{anchor:torch.factory}}

Returns the factory function of the Torch class ''name''. If the class name is invalid or if the class
has no factory, then returns ''nil''.

A Torch class is a class created with [[#torch.class|torch.class()]] or
[[#torch.newmetatable|torch.newmetatable()]].

A factory function is able to return a new (empty) object of its corresponding class. This is helpful for
[[File#torch.File.serialization|object serialization]].

====  [table] torch.getmetatable(string) ====
{{anchor:torch.getmetatable}}

Given a ''string'', returns a metatable corresponding to the Torch class described
by ''string''. Returns ''nil'' if the class does not exist.

A Torch class is a class created with [[#torch.class|torch.class()]] or
[[#torch.newmetatable|torch.newmetatable()]].

Example:
<file lua>
> for k,v in pairs(torch.getmetatable("torch.CharStorage")) do print(k,v) end
__index__       function: 0x1a4ba80
__typename      torch.CharStorage
write   function: 0x1a49cc0
__tostring__    function: 0x1a586e0
__newindex__    function: 0x1a4ba40
string  function: 0x1a4d860
__version       1
copy    function: 0x1a49c80
read    function: 0x1a4d840
__len__ function: 0x1a37440
fill    function: 0x1a375c0
resize  function: 0x1a37580
__index table: 0x1a4a080
size    function: 0x1a4ba20
</file>

====  [boolean] torch.isequal(object1, object2) ====
{{anchor:torch.isequal}}

If the two objects given as arguments are ''Lua'' tables (or Torch objects), then returns ''true'' if and only if the
tables (or Torch objects) have the same address in memory. Returns ''false'' in any other cases.

A Torch class is a class created with [[#TorchClass|torch.class()]] or
[[#torch.newmetatable|torch.newmetatable()]].

==== [string] torch.getdefaulttensortype() ====
{{anchor:torch.getdefaulttensortype}}

Returns a string representing the default tensor type currently in use
by Torch7.

====  [table] torch.getenv(function or userdata) ====
{{anchor:torch.getenv}}

Returns the Lua ''table'' environment of the given ''function'' or the given
''userdata''.  To know more about environments, please read the documentation
of [[http://www.lua.org/manual/5.1/manual.html#lua_setfenv|lua_setfenv()]]
and [[http://www.lua.org/manual/5.1/manual.html#lua_getfenv|lua_getfenv()]].

==== [number] torch.version(object) ====
{{anchor:torch.version}}

Returns the field <file lua>__version</file> of a given object. This might
be helpful to handle variations in a class over time.

====  [number] torch.pointer(object) ====
{{anchor:torch.pointer}}

Returns a unique id (pointer) of the given ''object'', which can be a Torch
object, a table, a thread or a function.

This is different from the //class// id returned by [[#torch.id|torch.id()]].

==== torch.setdefaulttensortype([typename]) ====
{{anchor:torch.setdefaulttensortype}}

Sets the default tensor type for all the tensors allocated from this
point on. Valid types are:
  * ''ByteTensor''
  * ''CharTensor''
  * ''ShortTensor''
  * ''IntTensor''
  * ''FloatTensor''
  * ''DoubleTensor''

====  torch.setenv(function or userdata, table) ====
{{anchor:torch.setenv}}

Assign ''table'' as the Lua environment of the given ''function'' or the given
''userdata''.  To know more about environments, please read the documentation
of [[http://www.lua.org/manual/5.1/manual.html#lua_setfenv|lua_setfenv()]]
and [[http://www.lua.org/manual/5.1/manual.html#lua_getfenv|lua_getfenv()]].

==== [object] torch.setmetatable(table, classname) ====
{{anchor:torch.setmetatable}}

Set the metatable of the given ''table'' to the metatable of the Torch
object named ''classname''.  This function has to be used with a lot
of care.

==== [table] torch.getconstructortable(string) ====
{{anchor:torch.getconstructortable}}

BUGGY
Return the constructor table of the Torch class specified by ''string'.