**- Undocumented Matlab - https://undocumentedmatlab.com -**

sprintfc – undocumented helper function

Posted By Yair Altman On November 27, 2013 | __5 Comments__

Every now and then I discover a useful built-in Matlab function, often by bumping into them within the m-code of standard functions. Such was the case, for example, of the * ismembc* function

- The requirement
^{[3]} - The standard solutions
^{[4]} **sprintfc**^{[5]}- London training course – Feb/Mar 2014
^{[6]}

The use-case of generating a cell-array of formatted strings is often encountered. Unfortunately, the standard * sprintf* function generates a single string, rather than a cell-array of strings. So, for example,

```
>> data = pi * (0:.5:2)
data =
0 1.5708 3.1416 4.7124 6.2832
>> sprintf('%.3f ',data)
ans =
0.000 1.571 3.142 4.712 6.283
```

This is nice, but not exactly what we need, which is a cell array that looks like this:

```
>> c % c is a 1x5 cell array
c =
'0.000' '1.571' '3.142' '4.712' '6.283'
```

There are several standard solution for getting the required cell array. A simple for-loop is one of the fastest of these, due to JIT optimizations in recent Matlab releases. Some of the other alternatives may seem very strange, but they perform faster than the simpler variants. Note that the following code should be run within a testing function, to remove extraneous influences on the timing (JIT compilation etc.):

```
% 1) Simple for-loop with sprintf
tic
for idx = 1 : 1000
c = {}; %initialize
% note: reallocations are not really a factor here, so don't bother preallocating
for dataElement = data
c{end+1} = sprintf('%.3f',dataElement);
end
end
toc
% Elapsed time is 0.076002 seconds.
% 2) Using arrayfun + num2str
tic
for idx = 1 : 1000
c = arrayfun(@(c) num2str(c,'%.3f'), data, 'uniform',false);
end
toc
% Elapsed time is 0.557993 seconds.
% 3) Using cellfun + num2str + num2cell
tic
for idx = 1 : 1000
c = cellfun(@(c) num2str(c,'%.3f'), num2cell(data), 'uniform',false);
end
toc
% Elapsed time is 0.566924 seconds.
% 4) Using num2cell + num2str
tic
for idx = 1 : 1000
c = num2cell(num2str(data','%.3f'),2)';
end
toc
% Elapsed time is 0.173026 seconds.
% 5) Using cellstr + num2str
tic
for idx = 1 : 1000
c = reshape(cellstr(num2str(data(:),'%.3f')),size(data));
end
toc
% Elapsed time is 0.175769 seconds.
% 6) Using num2cell + num2str (after Urs Schwartz & Jiro Doke)
tic
for idx = 1 : 1000
c = reshape(num2cell(num2str(data(:),'%.3f'),2),size(data));
end
toc
% Elapsed time is 0.170247 seconds.
% 7) Using strread + sprintf
tic
for idx = 1 : 1000
c = reshape(strread(sprintf(['%.3f','$'], data),'%s', 'delimiter','$'),size(data));
end
toc
% Elapsed time is 0.059457 seconds.
```

There are also some File Exchange contributions that do a similar thing, including num2cellstr ^{[7]} or mtx2charcell ^{[8]}, which basically implement the last two variants.

It turns out that the standard * num2str* function uses an undocumented built-in function

```
% 8) fastest and simplest - sprintfc
tic
for idx = 1 : 1000
c = sprintfc('%.3f',data);
end
toc
% Elapsed time is 0.015714 seconds.
```

This is a 35x speedup compared to * arrayfun/cellfun*, 5x speedup compared to the JIT-optimized for-loop, and 4x speedup compared to the fastest other variant. Useful indeed.

The syntax of the

`[cells, errorMsg, isLeft] = sprintfc(format, data, isImaginary);`

where `isImaginary`

is an optional flag (default=`false`

) indicating that data should be formatted as imaginary values with the specified magnitude:

```
>> data = pi * (-1:.5:1)
data =
-3.1416 -1.5708 0 1.5708 3.1416
>> sprintfc('%.3f', data, false)
ans =
'-3.142' '-1.571' '0.000' '1.571' '3.142'
>> sprintfc('%.3f', data, true)
ans =
'-3.142i' '-1.571i' '+0.000i' '+1.571i' '+3.142i'
```

The second returned argument is an `errorMsg`

string that is returned when * sprintfc* fails, typically due to an invalid format:

```
>> [c,errorMsg] = sprintfc('%r', data)
c =
{''}
errorMsg =
Invalid format.
```

The third returned value, `isLeft`

, is apparently ^{[9]} used to indicate whether the output cell-string is left-justified; namely, if the ‘-‘ flag is used within the format (thanks Yaroslav!). For example,

```
>> [cells, ~, isLeft] = sprintfc('%-8.5g', sqrt(2), false)
cells =
'1.4142 '
isLeft =
1
>> [cells, ~, isLeft] = sprintfc('%8.5g', sqrt(2), false)
cells =
' 1.4142'
isLeft =
0
```

* sprintfc* has apparently remained in its current stable state since it was first introduced in the last decade (sometime between Matlab release 7.1 [in 2005] and R2008a). I do not know why MathWorks chose to keep

If anyone finds any other similar useful built-ins, please do let me know.

`isImaginary`

] input flag, and its 2nd/3rd output args [`errorMsg`

and `isLeft`

]) is included in the new fully-documented/supported function I am planning a week of advanced Matlab training workshops/seminars in London in Feb/Mar 2014. I plan two separate courses:

**Advanced Matlab Programming**– 2 days, including best practices^{[11]}, preparing professional reports^{[12]}and performance tuning^{[13]}. US$ 999 until Jan 19, 2014; US$ 1199 for later registrations.**Advanced Matlab Visualization & GUI**– 3 days, including advanced visualization^{[14]}and GUI techniques^{[15]}. US$ 1499 until Jan 19, 2014; US$ 1799 for later registrations.

This is a unique opportunity to enhance your Matlab skills in a few days, at an affordable cost, by an established expert. This training is not provided anywhere else. If you have a specific topic that you would like me to discuss, then I would be happy to do it. In other words, I can customize the training to your specific needs, within the provided framework. More details on my training can be found here ^{[16]}.

If you are interested in the London courses or a private dedicated course, please Email me ^{[17]} (altmany at gmail dot com) for details.

Happy Hanukkah/Thanksgiving everyone ðŸ™‚

Categories: Medium risk of breaking in future versions, Stock Matlab function, Undocumented function

5 Comments (Open | Close)

Article printed from Undocumented Matlab: **https://undocumentedmatlab.com**

URL to article: **https://undocumentedmatlab.com/articles/sprintfc-undocumented-helper-function**

URLs in this post:

[1] * ismembc* function:

[2] * dtstr2dtnummx* function:

[3] The requirement: **http://undocumentedmatlab.com/blog/sprintfc-undocumented-helper-function/#requirement**

[4] The standard solutions: **http://undocumentedmatlab.com/blog/sprintfc-undocumented-helper-function/#standard**

[5] * sprintfc*:

[6] London training course – Feb/Mar 2014: **http://undocumentedmatlab.com/blog/sprintfc-undocumented-helper-function/#training**

[7] num2cellstr: **http://www.mathworks.com/matlabcentral/fileexchange/20639-num2cellstr**

[8] mtx2charcell: **http://www.mathworks.com/matlabcentral/fileexchange/10006-mtx2charcell**

[9] apparently: **http://undocumentedmatlab.com/blog/sprintfc-undocumented-helper-function/#comment-299838**

[10] * compose*:

[11] best practices: **http://undocumentedmatlab.com/courses/Matlab_Best_Practices_Course.pdf**

[12] preparing professional reports: **http://undocumentedmatlab.com/courses/Professional_Matlab_Reports.pdf**

[13] performance tuning: **http://undocumentedmatlab.com/courses/Matlab_Performance_Tuning_Course.pdf**

[14] advanced visualization: **http://undocumentedmatlab.com/courses/Matlab_Data_Visualization_Course.pdf**

[15] GUI techniques: **http://undocumentedmatlab.com/courses/Advanced_Matlab_GUI_Course.pdf**

[16] found here: **http://undocumentedmatlab.com/training/**

[17] Email me: **mailto:%20altmany%20@gmail.com?subject=Matlab%20training%20London&body=Hi%20Yair,%20&cc=;&bcc=**

[18] ismembc – undocumented helper function : **https://undocumentedmatlab.com/articles/ismembc-undocumented-helper-function**

[19] Undocumented feature() function : **https://undocumentedmatlab.com/articles/undocumented-feature-function**

[20] tic / toc – undocumented option : **https://undocumentedmatlab.com/articles/tic-toc-undocumented-option**

[21] cellfun – undocumented performance boost : **https://undocumentedmatlab.com/articles/cellfun-undocumented-performance-boost**

[22] Function call timeline profiling : **https://undocumentedmatlab.com/articles/function-call-timeline-profiling**

[23] Function definition meta-info : **https://undocumentedmatlab.com/articles/function-definition-meta-info**

Click here to print.

Copyright © Yair Altman - Undocumented Matlab. All rights reserved.

5 Comments To "sprintfc – undocumented helper function"

#1 CommentByYaroslav DonOn November 28, 2013 @ 01:47Yair hi,

After a short inspection I’ve come to the following conclusion: the third variable,

`isLeft`

, is used to indicate whether the output cell-string is left-justified; namely, if the`'-'`

flag is used within the format. For example,however,

Sincerely, Yaroslav

#2 CommentByYair AltmanOn November 28, 2013 @ 01:59@Yaroslav – ah! makes sense, also correlates with the

num2str.mcode. I’ve updated the main text accordingly. Thanks ðŸ™‚#3 CommentByMatteoOn November 28, 2013 @ 10:18Hi Yair

I tried to figure out how to do this, and with higher dimension cell arrays, when I was still a Matlab newbie. I was obviously ahead of myself, but with a ton of reading, testing, and asking around, I managed. But if I needed to do that again it is good to know about this function. Great tip, nice post. Thanks

#4 PingbackByClass object creation performance | Undocumented MatlabOn December 11, 2013 @ 09:57[…] Matlab application's performance and your Matlab programming skills in general, join my upcoming Advanced Matlab Programming course in London, March 2014 â€“ an intensive 2 day course on best practices, preparing professional […]

#5 PingbackByHow do I make a column vector into an array of strings? – DexPageOn July 1, 2015 @ 20:18[…] you can use undocumented built-in function sprintfc to convert a numeric array to a cell array of strings like so […]