matlab.lang.makeUniqueStrings

Construct unique strings from input strings

Syntax

U = matlab.lang.makeUniqueStrings(S)

U = matlab.lang.makeUniqueStrings(S,excludedStrings)

U = matlab.lang.makeUniqueStrings(S,whichStringsIdx)

U = matlab.lang.makeUniqueStrings(S,___, maxStringLength)

[U, modified] = matlab.lang.makeUniqueStrings(___)

Description

U = matlab.lang.makeUniqueStrings(S) constructs unique strings or character vectors, U, from input strings or character vectors, S, by appending an underscore and a number to duplicates.

U = matlab.lang.makeUniqueStrings(S,excludedStrings) constructs strings or character vectors that are unique within U and with respect to excludedStrings. The makeUniqueStrings function does not check excludedStrings for uniqueness.

U = matlab.lang.makeUniqueStrings(S,whichStringsIdx) specifies the subset of S to make unique within the entire set. makeUniqueStrings makes the elements in S(whichStringsIdx) unique among themselves and with respect to the remaining elements. makeUniqueStrings returns the remaining elements unmodified in U. Use this syntax when you have an string array or an array of character vectors, and need to check that only some elements are unique.

U = matlab.lang.makeUniqueStrings(S,___, maxStringLength) specifies the maximum length, maxStringLength, of elements in U. If makeUniqueStrings cannot make elements in S unique without exceeding maxStringLength, it returns an error. You can use this syntax with any of the input arguments of the previous syntaxes.

[U, modified] = matlab.lang.makeUniqueStrings(___) returns a logical array, modified, indicating the modified elements.

Examples

Construct Unique Character Vectors

Create a cell array of names and make each element unique.

S = {'John' 'Sue' 'Nick' 'John' 'Campion' 'John' 'Jason'};
U = matlab.lang.makeUniqueStrings(S)

U = 1x7 cell
    {'John'}    {'Sue'}    {'Nick'}    {'John_1'}    {'Campion'}    {'John_2'}    {'Jason'}

The makeUniqueStrings function appends the duplicate names in elements 3 and 5 with underscores and incrementing numbers.

Construct Unique Character Vectors and Specify Exclusions

Without specifying excluded values, make the character vectors in U unique.

S = {'John' 'Sue' 'Nick' 'John' 'Campion' 'John' 'Jason'};
U = matlab.lang.makeUniqueStrings(S)

U = 1x7 cell
    {'John'}    {'Sue'}    {'Nick'}    {'John_1'}    {'Campion'}    {'John_2'}    {'Jason'}

Specify that the character vector, 'Nick', should be excluded from the output.

U = matlab.lang.makeUniqueStrings(S, 'Nick')

U = 1x7 cell
    {'John'}    {'Sue'}    {'Nick_1'}    {'John_1'}    {'Campion'}    {'John_2'}    {'Jason'}

makeUniqueStrings excludes 'Nick' from U and instead modifies the first duplicate, found in element 3, to be 'Nick_1'.

Exclude workspace variables from the unique cell array.

Sue = 42;
U = matlab.lang.makeUniqueStrings(S, who)

U = 1x7 cell
    {'John'}    {'Sue_1'}    {'Nick'}    {'John_1'}    {'Campion'}    {'John_2'}    {'Jason'}

Since 'Sue' exists in the workspace, makeUniqueStrings makes this character vector unique by appending an underscore and number.

Construct Unique Elements for Specified Array Indices

Create an array of character vectors and make only the first four elements unique.

S = {'quiz' 'quiz' 'quiz' 'exam' 'quiz' 'exam'};
U = matlab.lang.makeUniqueStrings(S, 1:4)

U = 1x6 cell
    {'quiz_1'}    {'quiz_2'}    {'quiz_3'}    {'exam_1'}    {'quiz'}    {'exam'}

The first four elements in U are unique among themselves, and among the remaining character vectors in elements 5 and 6 ('quiz' and 'exam'). Alternatively, you can use a logical array instead of a range of linear indices to achieve the same results: U = matlab.lang.makeUniqueStrings(S, [true true true true false false]) or U = matlab.lang.makeUniqueStrings(S, logical([1 1 1 1 0 0])).

Append a duplicate 'quiz' onto the end of S and make the first four elements unique.

S{end+1} = 'quiz'

S = 1x7 cell
    {'quiz'}    {'quiz'}    {'quiz'}    {'exam'}    {'quiz'}    {'exam'}    {'quiz'}

U = matlab.lang.makeUniqueStrings(S, 1:4)

U = 1x7 cell
    {'quiz_1'}    {'quiz_2'}    {'quiz_3'}    {'exam_1'}    {'quiz'}    {'exam'}    {'quiz'}

The character vectors that makeUniqueStrings checks are still unique among themselves and among the remaining elements. Since makeUniqueStrings does not check any elements after element 4, duplicate character vectors remain.

Construct Unique Character Vectors with Maximum Length

Create an array from S where the first three elements are unique and the maximum length of each string is 5.

S = {'sampleData' 'sampleData' 'sampleData' 'sampleData'};
U = matlab.lang.makeUniqueStrings(S, 1:3, 5)

U = 1x4 cell
    {'sampl'}    {'sam_1'}    {'sam_2'}    {'sampleData'}

The first element is truncated to 5 characters. The second and third elements are truncated to 3 characters to allow makeUniqueStrings to append an underscore and number, and still not exceed 5 characters.

Determine Modified Strings

Create a cell array of names and make each element unique. The output modified shows which elements of the input have been modified.

S = ["John"    "Sue"    "Nick"    "John"    "Campion"    "John"    "Jason"];
[U, modified] = matlab.lang.makeUniqueStrings(S)

U = 1x7 string
    "John"    "Sue"    "Nick"    "John_1"    "Campion"    "John_2"    "Jason"

modified = 1x7 logical array

   0   0   0   1   0   1   0

Input Arguments

S — Input values

character vector | cell array of character vectors | string array

Input strings, specified as a character vector, cell array of character vectors, or string array.

excludedStrings — Strings to exclude

character vector | cell array of character vectors | string array

Character vectors to exclude from U, specified as a character vector, cell array of character vectors, or string array.

Example: 'dontDuplicateThis'

Example: {'excludeS1' 'excludeS2'}

Example: ["excludeThis" "andThis"]

Example: who

whichStringsIdx — Subset of strings to make unique

range of linear indices or logical array

Subset of Sto make unique within the entire set, specified as a range of linear indices or as a logical array with the same size and shape as S. If there are duplicates in S, the makeUniqueStrings function only modifies those specified by whichStringsIdx.

If whichStringsIdx is a logical array, elements are checked for uniqueness when the array element in the same position has a value of true.

Example: 1:5, logical([1 0 1]), [true false true]

maxStringLength — Maximum length of strings

integer

Maximum length of strings in U, specified as an integer. If makeUniqueStrings cannot make elements in S unique without exceeding maxStringLength, it returns an error.

Output Arguments

U — Unique strings

character vector | cell array of character vectors | string array

Unique strings, returned as a character vector, cell array of character vectors, or string array. The output has the same dimension as the input, S.

modified — Indicator of modified elements

logical scalar | logical array

Indicator of modified elements, returned as a logical scalar or array and having the same dimension as the input, S. A value of 1 (true) indicates that makeUniqueStrings modified the element in the corresponding location. A value of 0 (false) indicates that makeUniqueStrings did not need to modify the element in the corresponding location.

Tips

• To ensure that input values are valid and unique, use matlab.lang.makeValidName before matlab.lang.makeUniqueStrings.

  S = {'my.Name','my_Name','my_Name'};
  validValues = matlab.lang.makeValidName(S)
  validUniqueValues = matlab.lang.makeUniqueStrings(validValues,...
      {},namelengthmax)

  validValues = 
  
      'my_Name'    'my_Name'    'my_Name'
  
  
  validUniqueValues = 
  
      'my_Name'    'my_Name_1'    'my_Name_2'

Version History

Introduced in R2014a