{"id":2798,"date":"2018-04-13T05:35:49","date_gmt":"2018-04-13T10:35:49","guid":{"rendered":"https:\/\/blogs.mathworks.com\/loren\/?p=2798"},"modified":"2018-04-13T05:35:49","modified_gmt":"2018-04-13T10:35:49","slug":"accept-string-inputs-in-your-code","status":"publish","type":"post","link":"https:\/\/blogs.mathworks.com\/loren\/2018\/04\/13\/accept-string-inputs-in-your-code\/","title":{"rendered":"Accept String Inputs in Your Code"},"content":{"rendered":"\r\n<div class=\"content\"><!--introduction--><p>Today I'd like to introduce a guest blogger, Stephen Doe, who works for the MATLAB Documentation team here at MathWorks. In today's post, Stephen discusses how, and why, you might want to update your code to accept string arrays as inputs.<\/p><!--\/introduction--><h3>Contents<\/h3><div><ul><li><a href=\"#4ca2e170-ae8c-4983-a497-6cff4adfffe4\">What Are Strings?<\/a><\/li><li><a href=\"#ef5f3183-347d-47bc-8267-83b02935a447\">Public Service Announcement!<\/a><\/li><li><a href=\"#b293c5b2-66aa-4f5b-9f5f-b5f825e4a1d2\">How to Make Your Code Work with Strings<\/a><\/li><li><a href=\"#31f918dc-e5c5-4d0a-9ec5-faeecc03fecb\">Pulling More Strings<\/a><\/li><\/ul><\/div><h4>What Are Strings?<a name=\"4ca2e170-ae8c-4983-a497-6cff4adfffe4\"><\/a><\/h4><p>In R2016b, MATLAB&reg; introduced the <a href=\"https:\/\/www.mathworks.com\/help\/matlab\/ref\/string.html\"><tt>string<\/tt><\/a> data type as a new data type for text. Each element of a string array stores a sequence of characters. You can use standard array indexing and operations on string arrays, along with string manipulation functions introduced in R2016b. Also, you can use many MATLAB functions (such as <tt>sort<\/tt> and <tt>unique<\/tt>) on string arrays.<\/p><p>Here's a short example. Start with some text you can store as one string--or as a string <i>scalar<\/i>, a term we use to describe a string array with one element. As of R2017a, you can use double-quotes to create a string. (Single-quotes still create a character vector.)<\/p><pre class=\"codeinput\">str = <span class=\"string\">\"A horse! a horse! My kingdom for a horse!\"<\/span>\r\n<\/pre><pre class=\"codeoutput\">str = \r\n    \"A horse! a horse! My kingdom for a horse!\"\r\n<\/pre><p>If you use the <tt>split<\/tt> function to split that string on space characters, then the result is a string array with nine elements. Instead of getting a cell array, you get a homogeneous array storing text--an array that has the same data type you started with. The <tt>split<\/tt> function returns the string array as a column vector. Let's reshape it as a row vector of strings for more compact display.<\/p><pre class=\"codeinput\">str = split(str);\r\nstr = str'\r\n<\/pre><pre class=\"codeoutput\">str = \r\n  1&times;9 string array\r\n  Columns 1 through 8\r\n    \"A\"    \"horse!\"    \"a\"    \"horse!\"    \"My\"    \"kingdom\"    \"for\"    \"a\"\r\n  Column 9\r\n    \"horse!\"\r\n<\/pre><p>String arrays now provide a powerful way to deal with text in your data. As you work with your text in a string array, you never have to resort to cell arrays or curly brace indexing. I won't belabor the point, because Loren already has published some wonderful guest posts on using string arrays. If you are looking for more examples using strings, see: <a href=\"https:\/\/blogs.mathworks.com\/loren\/2016\/09\/15\/introducing-string-arrays\/\">Introducing String Arrays<\/a>, <a href=\"https:\/\/blogs.mathworks.com\/loren\/2016\/12\/22\/singing-the-praises-of-strings\/\">Singing the Praises of Strings<\/a>, and <a href=\"https:\/\/blogs.mathworks.com\/loren\/2017\/04\/24\/working-with-text-in-matlab\/\">Working with Text in MATLAB<\/a>.<\/p><p>And of course, you can find the documentation for string arrays at <a href=\"https:\/\/www.mathworks.com\/help\/matlab\/characters-and-strings.html\">Characters and Strings<\/a>.<\/p><h4>Public Service Announcement!<a name=\"ef5f3183-347d-47bc-8267-83b02935a447\"><\/a><\/h4><p>A few paragraphs ago, I said that \"many\" MATLAB functions now accept string arrays as inputs arguments. In fact, in a future release nearly all MathWorks&reg; products will work with string arrays as inputs.<\/p><p>Here's what we mean when we say that a product \"works with\" string arrays as inputs:<\/p><div><ul><li>If an input argument can be a single piece of text, then you can specify it as a character vector <b>or<\/b> as a string scalar. That is, you can use either single-quotes or double-quotes.<\/li><\/ul><\/div><div><ul><li>If an input argument can contain multiple pieces of text, then you can specify it as a cell array of character vectors <b>or<\/b> as a string array.<\/li><\/ul><\/div><p>We're holding to this pattern in old functions where we are adding support for string arrays, and in new functions going forward. Consider the <tt>split<\/tt> function I used to split a string. It works just as well on character vectors or cell arrays of character vectors as it does on strings. (Note that functions which have always returned a character vector in previous releases, such as the <tt>fileread<\/tt> function, will continue to do so for compatibility.)<\/p><p>We think this approach is the most seamless way to support use of string arrays throughout our products. Our advice is to take the same approach in your own code. If you maintain code of your own, or write code for other MATLAB users, then it is to your advantage to update your code to accept string arrays as inputs, while maintaining support for the older types for storing text.<\/p><h4>How to Make Your Code Work with Strings<a name=\"b293c5b2-66aa-4f5b-9f5f-b5f825e4a1d2\"><\/a><\/h4><p>Right now, you are thinking, \"Great! But how do I do that?\" (Well, perhaps \"great\" is not the exact word that came to mind.)<\/p><p>To help you update your code, the R2018a documentation provides guidelines to <a href=\"https:\/\/www.mathworks.com\/help\/matlab\/matlab_prog\/update-your-code-to-accept-strings.html\">Update Your Code to Accept Strings<\/a>. You can apply these guidelines to your code now. The guidelines, and our documentation, also provide links to helper functions, such as <tt>convertStringsToChars<\/tt>, that smooth the way to accepting strings in your code.<\/p><p>Here is a short example that shows two ways to put these guidelines into action. I'll start with a fast and simple way that uses one of our helper functions. Then I'll follow with another way that is a little more time consuming, but is also a little more forward-looking.<\/p><p>Suppose this code is your original function to abbreviate the name of a city using its first three letters, making those letters uppercase. Up to now, you have specified a city's name as a character vector. For example, if the input argument is <tt>'Boston'<\/tt>, then the output argument is <tt>'BOS'<\/tt>.<\/p><pre class=\"language-matlab\"><span class=\"keyword\">function<\/span> abr = abbreviateName(str)\r\n    abr = upper(str(1:3));\r\n<span class=\"keyword\">end<\/span>\r\n<\/pre><p>If your user instead specifies the <b>string<\/b> <tt>\"Boston\"<\/tt> as the input argument, then there will be a syntax error. For a string array, the syntax <tt>str(1:3)<\/tt> means, return the first, second, and third strings as a three-element string array. But <tt>\"Boston\"<\/tt> all by itself is a 1-by-1 string array!<\/p><p>One way to support both character vectors and strings is to use the helper function <a href=\"https:\/\/www.mathworks.com\/help\/matlab\/ref\/convertstringstochars.html\"><tt>convertStringsToChars<\/tt><\/a> at the beginning of the original code. <tt>convertStringsToChars<\/tt> processes an arbitrary number of input arguments and, if any of them are strings, converts them. It leaves all other data types alone.<\/p><pre class=\"language-matlab\"><span class=\"keyword\">function<\/span> abr = abbreviateName(str)\r\n    str = convertStringsToChars(str);\r\n    abr = upper(str(1:3));\r\n<span class=\"keyword\">end<\/span>\r\n<\/pre><p>With the helper function, you can accept input string arrays without altering any of the code that follows. Also, the output argument type does not differ from the type returned by the original code.<\/p><p>A second way is to use one of the new functions for text manipulation, such as <a href=\"https:\/\/www.mathworks.com\/help\/matlab\/ref\/extractbefore.html\"><tt>extractBefore<\/tt><\/a>. These new functions also work with character vectors and cell arrays of character vectors. And so, this new version of <tt>abbreviateName<\/tt> works the same way for inputs of any text data type.<\/p><pre class=\"language-matlab\"><span class=\"keyword\">function<\/span> abr = abbreviateName(str)\r\n    abr = extractBefore(str,4);\r\n    abr = upper(abr);\r\n<span class=\"keyword\">end<\/span>\r\n<\/pre><p>While this code supports both strings and character vectors, I did have to rewrite the code. Also, this code returns a string if the input is a string. The original code always returned a character vector.<\/p><h4>Pulling More Strings<a name=\"31f918dc-e5c5-4d0a-9ec5-faeecc03fecb\"><\/a><\/h4><p>Which way is the right way for you? Well, that is the \"choose your own adventure\" part. If you are doing a lot of work with text, then it might be time for you to do a deep dive into your code and rewrite its internals to use string arrays. If not, then use <tt>convertStringsToChars<\/tt> and minimize the pain of updating your code. On either path, look for help in our <a href=\"https:\/\/www.mathworks.com\/help\/matlab\/matlab_prog\/update-your-code-to-accept-strings.html\">guidelines<\/a>.<\/p><p>And if you have things to say about string arrays, or your efforts to update your own code, then let us know <a href=\"https:\/\/blogs.mathworks.com\/loren\/?p=2798#respond\">here<\/a>.<\/p><script language=\"JavaScript\"> <!-- \r\n    function grabCode_0175c8df393c4a61aa5e4f7bd969c3a5() {\r\n        \/\/ Remember the title so we can use it in the new page\r\n        title = document.title;\r\n\r\n        \/\/ Break up these strings so that their presence\r\n        \/\/ in the Javascript doesn't mess up the search for\r\n        \/\/ the MATLAB code.\r\n        t1='0175c8df393c4a61aa5e4f7bd969c3a5 ' + '##### ' + 'SOURCE BEGIN' + ' #####';\r\n        t2='##### ' + 'SOURCE END' + ' #####' + ' 0175c8df393c4a61aa5e4f7bd969c3a5';\r\n    \r\n        b=document.getElementsByTagName('body')[0];\r\n        i1=b.innerHTML.indexOf(t1)+t1.length;\r\n        i2=b.innerHTML.indexOf(t2);\r\n \r\n        code_string = b.innerHTML.substring(i1, i2);\r\n        code_string = code_string.replace(\/REPLACE_WITH_DASH_DASH\/g,'--');\r\n\r\n        \/\/ Use \/x3C\/g instead of the less-than character to avoid errors \r\n        \/\/ in the XML parser.\r\n        \/\/ Use '\\x26#60;' instead of '<' so that the XML parser\r\n        \/\/ doesn't go ahead and substitute the less-than character. \r\n        code_string = code_string.replace(\/\\x3C\/g, '\\x26#60;');\r\n\r\n        copyright = 'Copyright 2018 The MathWorks, Inc.';\r\n\r\n        w = window.open();\r\n        d = w.document;\r\n        d.write('<pre>\\n');\r\n        d.write(code_string);\r\n\r\n        \/\/ Add copyright line at the bottom if specified.\r\n        if (copyright.length > 0) {\r\n            d.writeln('');\r\n            d.writeln('%%');\r\n            if (copyright.length > 0) {\r\n                d.writeln('% _' + copyright + '_');\r\n            }\r\n        }\r\n\r\n        d.write('<\/pre>\\n');\r\n\r\n        d.title = title + ' (MATLAB code)';\r\n        d.close();\r\n    }   \r\n     --> <\/script><p style=\"text-align: right; font-size: xx-small; font-weight:lighter;   font-style: italic; color: gray\"><br><a href=\"javascript:grabCode_0175c8df393c4a61aa5e4f7bd969c3a5()\"><span style=\"font-size: x-small;        font-style: italic;\">Get \r\n      the MATLAB code <noscript>(requires JavaScript)<\/noscript><\/span><\/a><br><br>\r\n      Published with MATLAB&reg; R2018a<br><\/p><\/div><!--\r\n0175c8df393c4a61aa5e4f7bd969c3a5 ##### SOURCE BEGIN #####\r\n%% Accept String Inputs in Your Code\r\n% Today I'd like to introduce a guest blogger, Stephen Doe, who works for\r\n% the MATLAB Documentation team here at MathWorks. In today's post, Stephen\r\n% discusses how, and why, you might want to update your code to accept\r\n% string arrays as inputs.\r\n%\r\n%% What Are Strings?\r\n% In R2016b, MATLAB(R) introduced the\r\n% <https:\/\/www.mathworks.com\/help\/matlab\/ref\/string.html |string|> data\r\n% type as a new data type for text. Each element of a string array stores a\r\n% sequence of characters. You can use standard array indexing and\r\n% operations on string arrays, along with string manipulation functions\r\n% introduced in R2016b. Also, you can use many MATLAB functions (such as\r\n% |sort| and |unique|) on string arrays.\r\n%\r\n% Here's a short example. Start with some text you can store as one\r\n% stringREPLACE_WITH_DASH_DASHor as a string _scalar_, a term we use to describe a string array\r\n% with one element. As of R2017a, you can use double-quotes to create a\r\n% string. (Single-quotes still create a character vector.)\r\nstr = \"A horse! a horse! My kingdom for a horse!\"\r\n\r\n%%\r\n% If you use the |split| function to split that string on space characters,\r\n% then the result is a string array with nine elements. Instead of getting\r\n% a cell array, you get a homogeneous array storing textREPLACE_WITH_DASH_DASHan array that has\r\n% the same data type you started with. The |split| function returns the\r\n% string array as a column vector. Let's reshape it as a row vector of\r\n% strings for more compact display.\r\nstr = split(str);\r\nstr = str'\r\n\r\n%%\r\n% String arrays now provide a powerful way to deal with text in your data.\r\n% As you work with your text in a string array, you never have to resort to\r\n% cell arrays or curly brace indexing. I won't belabor the point, because\r\n% Loren already has published some wonderful guest posts on using string\r\n% arrays. If you are looking for more examples using strings, see:\r\n% <https:\/\/blogs.mathworks.com\/loren\/2016\/09\/15\/introducing-string-arrays\/\r\n% Introducing String Arrays>,\r\n% <https:\/\/blogs.mathworks.com\/loren\/2016\/12\/22\/singing-the-praises-of-strings\/\r\n% Singing the Praises of Strings>, and\r\n% <https:\/\/blogs.mathworks.com\/loren\/2017\/04\/24\/working-with-text-in-matlab\/\r\n% Working with Text in MATLAB>.\r\n%\r\n% And of course, you can find the documentation for string arrays at <https:\/\/www.mathworks.com\/help\/matlab\/characters-and-strings.html Characters and\r\n% Strings>.\r\n\r\n%% Public Service Announcement!\r\n% A few paragraphs ago, I said that \"many\" MATLAB functions now accept\r\n% string arrays as inputs arguments. In fact, in a future release nearly\r\n% all MathWorks(R) products will work with string arrays as inputs.\r\n%\r\n% Here's what we mean when we say that a product \"works with\" string arrays\r\n% as inputs:\r\n%\r\n% * If an input argument can be a single piece of text, then you can\r\n% specify it as a character vector *or* as a string scalar. That is, you\r\n% can use either single-quotes or double-quotes.\r\n%\r\n% * If an input argument can contain multiple pieces of text, then you can\r\n% specify it as a cell array of character vectors *or* as a string array.\r\n%\r\n% We're holding to this pattern in old functions where we are adding\r\n% support for string arrays, and in new functions going forward. Consider\r\n% the |split| function I used to split a string. It works just as well on\r\n% character vectors or cell arrays of character vectors as it does on\r\n% strings. (Note that functions which have always returned a character\r\n% vector in previous releases, such as the |fileread| function, will\r\n% continue to do so for compatibility.)\r\n%\r\n% We think this approach is the most seamless way to support use of string\r\n% arrays throughout our products. Our advice is to take the same approach\r\n% in your own code. If you maintain code of your own, or write code for\r\n% other MATLAB users, then it is to your advantage to update your code to\r\n% accept string arrays as inputs, while maintaining support for the older\r\n% types for storing text.\r\n\r\n%% How to Make Your Code Work with Strings\r\n% Right now, you are thinking, \"Great! But how do I do that?\"\r\n% (Well, perhaps \"great\" is not the exact word that came to mind.)\r\n%\r\n% To help you update your code, the R2018a documentation provides\r\n% guidelines to\r\n% <https:\/\/www.mathworks.com\/help\/matlab\/matlab_prog\/update-your-code-to-accept-strings.html\r\n% Update Your Code to Accept Strings>. You can apply these guidelines to\r\n% your code now. The guidelines, and our documentation, also provide links\r\n% to helper functions, such as |convertStringsToChars|, that smooth the way\r\n% to accepting strings in your code.\r\n%\r\n% Here is a short example that shows two ways to put these guidelines into\r\n% action. I'll start with a fast and simple way that uses one of our helper\r\n% functions. Then I'll follow with another way that is a little more time\r\n% consuming, but is also a little more forward-looking.\r\n%\r\n% Suppose this code is your original function to abbreviate the name of a\r\n% city using its first three letters, making those letters uppercase. Up to\r\n% now, you have specified a city's name as a character vector. For example,\r\n% if the input argument is |'Boston'|, then the output argument is |'BOS'|.\r\n%\r\n%   function abr = abbreviateName(str)\r\n%       abr = upper(str(1:3));\r\n%   end\r\n%\r\n% If your user instead specifies the *string* |\"Boston\"| as the input\r\n% argument, then there will be a syntax error. For a string array, the\r\n% syntax |str(1:3)| means, return the first, second, and third strings as a\r\n% three-element string array. But |\"Boston\"| all by itself is a 1-by-1\r\n% string array!\r\n%\r\n% One way to support both character vectors and strings is to use the\r\n% helper function\r\n% <https:\/\/www.mathworks.com\/help\/matlab\/ref\/convertstringstochars.html\r\n% |convertStringsToChars|> at the beginning of the original code.\r\n% |convertStringsToChars| processes an arbitrary number of input arguments\r\n% and, if any of them are strings, converts them. It leaves all other data\r\n% types alone.\r\n%\r\n%   function abr = abbreviateName(str)\r\n%       str = convertStringsToChars(str);\r\n%       abr = upper(str(1:3));\r\n%   end\r\n%\r\n% With the helper function, you can accept input string arrays without\r\n% altering any of the code that follows. Also, the output argument type\r\n% does not differ from the type returned by the original code.\r\n% \r\n% A second way is to use one of the new functions for text manipulation,\r\n% such as <https:\/\/www.mathworks.com\/help\/matlab\/ref\/extractbefore.html\r\n% |extractBefore|>. These new functions also work with character vectors\r\n% and cell arrays of character vectors. And so, this new version of\r\n% |abbreviateName| works the same way for inputs of any text data type.\r\n%\r\n%   function abr = abbreviateName(str)\r\n%       abr = extractBefore(str,4);\r\n%       abr = upper(abr);\r\n%   end\r\n%\r\n% While this code supports both strings and character vectors, I did have\r\n% to rewrite the code. Also, this code returns a string if the input is a\r\n% string. The original code always returned a character vector.\r\n%\r\n%% Pulling More Strings\r\n% Which way is the right way for you? Well, that is the \"choose your own\r\n% adventure\" part. If you are doing a lot of work with text, then it might\r\n% be time for you to do a deep dive into your code and rewrite its\r\n% internals to use string arrays. If not, then use |convertStringsToChars|\r\n% and minimize the pain of updating your code. On either path, look for\r\n% help in our\r\n% <https:\/\/www.mathworks.com\/help\/matlab\/matlab_prog\/update-your-code-to-accept-strings.html\r\n% guidelines>.\r\n%\r\n% And if you have things to say about string arrays, or your efforts to\r\n% update your own code, then let us know\r\n% <https:\/\/blogs.mathworks.com\/loren\/?p=2798#respond here>.\r\n\r\n##### SOURCE END ##### 0175c8df393c4a61aa5e4f7bd969c3a5\r\n-->","protected":false},"excerpt":{"rendered":"<!--introduction--><p>Today I'd like to introduce a guest blogger, Stephen Doe, who works for the MATLAB Documentation team here at MathWorks. In today's post, Stephen discusses how, and why, you might want to update your code to accept string arrays as inputs.... <a class=\"read-more\" href=\"https:\/\/blogs.mathworks.com\/loren\/2018\/04\/13\/accept-string-inputs-in-your-code\/\">read more >><\/a><\/p>","protected":false},"author":39,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":[],"categories":[16,6,2],"tags":[],"_links":{"self":[{"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/posts\/2798"}],"collection":[{"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/users\/39"}],"replies":[{"embeddable":true,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/comments?post=2798"}],"version-history":[{"count":2,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/posts\/2798\/revisions"}],"predecessor-version":[{"id":2802,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/posts\/2798\/revisions\/2802"}],"wp:attachment":[{"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/media?parent=2798"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/categories?post=2798"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blogs.mathworks.com\/loren\/wp-json\/wp\/v2\/tags?post=2798"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}