## For instruction on writing tutorials
## http://www.ros.org/wiki/WritingTutorials
####################################
##FILL ME IN
####################################
## for a custom note with links:
## note =
## for the canned note of "This tutorial assumes that you have completed the previous tutorials:" just add the links 
## note.0= [[ecl_containers/Tutorials/Arrays|Arrays]]
## note.1= [[ecl_containers/Tutorials/Arrays|Stencils]]
## descriptive title for the tutorial
## title = Container Utilities
## multi-line description to be displayed in search 
## description = container formatters and converters.
## the next tutorial description (optional)
## next =
## links to next tutorial (optional)
## next.0.link=
## next.1.link=
## what level user is this tutorial for 
## level= IntermediateCategory
## keywords = ecl container utilities
####################################

<<IncludeCSTemplate(TutorialCSHeaderTemplate)>>

== Formatters ==

Currently there is only limited support for formatters of the array and stencil classes classes:

 * precision/width formatting for float arrays.
 * hex formatting for byte arrays (signed char/char/unsigned char).
 * default formatting for other types of arrays (provided they have the required Format for the element type).
 * formatting extends to stencils operating on the array.

{{{
#!cplusplus
#include <ecl/array.hpp>

Array<unsigned char>::Formatter format;
Array<unsigned char> array;
array << 0x01, 0x02, 0x03, 0x04;
std::cout << format(array) << std::endl;
// OR
#include <ecl/array.hpp>
#include <ecl/format.hpp>

Format< Array<unsigned char> > format;
Array<unsigned char> array;
array << 0x01, 0x02, 0x03, 0x04;
std::cout << format(array) << std::endl;
}}}

See also [[ecl_formatters]].

== Byte Array Converters ==

These are often useful for interacting with io devices.

Some converters utilising the `FromByteArray` template class from [[ecl_converters]] have specialisations here for arrays and stencils respectively. These allow conversion to integers of any time from a corresponding, little endian filled array/stencil of chars.

{{{
#!cplusplus
typedef Array<char, 4> ByteArray;
ByteArray byte_array;

byte_array << 0x01, 0x02, 0x03;
ecl::Converter<int,ByteStencil> toInt;
std::cout << "Conversion: " << toInt(byte_array) << std::endl; // results in 197121
std::cout << "Conversion: " << toInt(byte_array.stencil(0,2)) << std::endl; // only first two bytes -> 513
}}}

and going the other way, we pass it the byte array for storage when converting (works on both arrays and stencils)...

{{{
#!cplusplus
Array<char,20> byte_array = Array<char,20>::Constant(0x00);
Stencil< Array<char, 20> > stencil = byte_array.stencil(2,4);
ecl::Converter< Stencil< Array<char, 20> >, ecl::int32 > fromInt;
fromInt(stencil, ecl::int32(197121));
std::cout << byte_array << std::endl;    // 0x00, 0x00, 0x01, 0x02, 0x03, 0x00, 0x00, 0x00, ...
std::cout << stencil << std::endl;       // 0x01, 0x02, 0x03, 0x00
}}}

## AUTOGENERATED DO NOT DELETE 
## TutorialCategory
## FILL IN THE STACK TUTORIAL CATEGORY HERE