Click or drag to resize

IMcFeaturesList2ValidateName Method

Checks that a supplied name is suitable for being added to the list and optionally checks for a name collision with an existing object.

Namespace:  MediaCy.IQL.Features
Assembly:  MediaCy.IQL.Features (in MediaCy.IQL.Features.dll) Version: 10.0.6912.0
Syntax
VB
Copy
Function ValidateName ( 
	NameToCheck As String,
	<OutAttribute> ByRef ValidatedName As String,
	Optional bTestForCollision As Boolean = false
) As Integer

Parameters

NameToCheck
Type: SystemString
A name string to be checked for validity, and optionally for collision with other names already in the list.
ValidatedName
Type: SystemString
The NameToCheck argument is made valid by removing illegal leading and trailing characters and then replacing all illegal interior characters with underscores and truncating the result to a maximum of 31 characters (see Example 1). If the bTestForCollision argument is given and True, then the cleaned-up name is tested to see if there is already a matching one in the list (using a case-insensitive comparison). If so, then a number starting at 1 is appended to the returned ValidatedName (see Example 2).
bTestForCollision (Optional)
Type: SystemBoolean
If given and True, then the cleaned-up name is tested to see if there is already a matching one in the list (using a case-insensitive comparison). If so, then a number is appended to the returned ValidatedName (see Example 2); if the name does not already have a trailing number, then numbering is started at 1. If not given or False, then no collision test is done, and the ValidatedName might match one already in the list.

Return Value

Type: Int32
Plus or minus the number of characters in the ValidatedName. This will be a positive number if the supplied NameToCheck did not have to be changed to be valid or to avoid a collision (if bTestForCollision is True). If a negative number, then the NameToCheck needed to be changed in some way, either because it was ill-formed or to avoid a collision. Note that it is possible that no ValidateName of even 1 character in length might be recoverable from the NameToCheck (e.g., it might be all spaces). In this case, zero is returned and the ValidatedName will be an empty string (see Example 1).

Implements

IMcFeaturesListValidateName(String, String, Boolean)
Remarks
The Add method requires that names start and end with a displayable, non-space character and consist of only displayable characters plus the space character. A cleaned up name is provided via the ValidatedName argument.
Examples
VB
Copy
'Example 1 - validate a name with errors
Dim strValidated As String
Dim nValid As Long
nValid = AoiList.ValidateName( " 1 2 Buckle your shoe.", strValidated)
if nValid = 0 Then
Debug.Print "The supplied name name could not be made into a valid one."
Else
Debug.Print "The validated name is """ & strValidated & """ and has " & Abs(nValid) & " characters."
' The validated name is "1 2 Buckle your shoe." and has 21 characters
End If
'Example 2 - generate a no-collision name
nValid = AoiList.ValidateName( "Rectangle 5", strValidated, True)
Debug.Print "The no collision name is """ & strValidated & """ and has " & Abs(nValid) & " characters."
' The validated name is "Rectangle 6" and has 11 characters
See Also