Contenu

# Service ScriptForge.String

Le service String fournit une collection de méthodes pour le traitement des chaînes. Ces méthodes peuvent être utilisées pour :

- Valider le contenu des chaînes

- Formater les chaînes en coupant, justifiant ou enveloppant leur contenu

- Utiliser des expressions régulières pour rechercher et remplacer des sous-chaînes

- Appliquer des algorithmes de hachage sur des chaînes, etc.

## Définitions

### Sauts de ligne

Le service String reconnaît les sauts de ligne suivants :

Nom symbolique | nombre ASCII
--- | ---
Saut de ligne Tabulation verticale Retour chariot Retour chariot + saut de ligne Séparateur de fichier Séparateur de groupe Séparateur d'enregistrement Ligne suivante Séparateur de ligne Séparateur de paragraphe | 10 12 13 13 + 10 28 29 30 133 8232 8233

### Espaces

Le service String reconnaît les espaces suivants :

Nom symbolique | Nombre ASCII
--- | ---
Espace Tabulation horizontale Saut de ligne Tabulation verticale Saut de page Retour chariot Ligne suivante Espace insécable Ligne séparateur Séparateur de paragraphe | 32 9 10 11 12 13 133 160 8232 8233

### Séquences d'échappement

Vous trouverez ci-dessous une liste de séquences d'échappement pouvant être utilisées dans des chaînes.

Séquence d'échappement | Nom symbolique | Nombre ASCII
--- | --- | ---
\n \r \t | Saut de ligne Retour chariot Onglet horizontal | 10 13 9

Pour que la séquence d'échappement "\n" soit interprétée comme une chaîne réelle, utilisez simplement "\\n" au lieu de "\" & Chr(10).

### Caractères non imprimables :

Les caractères définis dans la base de données de caractères Unicode comme "Autre" ou "Séparateur" sont considérés comme des caractères non imprimables.

Les caractères de contrôle (code ASCII <= 0x1F) sont également considérés comme non imprimables.

### Guillemets à l'intérieur des chaînes :

Pour ajouter des guillemets dans les chaînes, utilisez \' (guillemets simples) ou \" (guillemets doubles). Par exemple :

- La chaîne [str\'i\'ng] est interprétée comme [str'i'ng]

- La chaîne [str\"i\"ng] est interprétée comme [str"i"ng]

## Invocation du service

Avant de pouvoir utiliser le service ScriptForge.String, la bibliothèque ScriptForge doit être chargée en utilisant :

##### En Basic :

          GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

Charger la bibliothèque créera l'objet SF_String qui peut être utilisé pour appeler les méthode dans le service String.

Les extraits de code suivants montrent les trois façons d'appeler des méthodes à partir du service String (la méthode Capitalize est utilisée à titre d'exemple) :

        Dim s as String : s = "abc def"
        s = SF_String.Capitalize(s) ' Abc Def

        Dim s as String : s = "abc def"
        Dim svc : svc = SF_String
        s = svc.Capitalize(s) ' Abc Def

        Dim s as String : s = "abc def"
        Dim svc : svc = CreateScriptService("String")
        s = svc.Capitalize(s) ' Abc Def

##### En Python

L'extrait de code ci-dessous illustre comment invoquer des méthodes à partir du service String dans des scripts Python. La méthode IsIPv4 est utilisée comme exemple.

        from scriptforge import CreateScriptService
        svc = CreateScriptService("String")
        ip_address = '192.168.0.14'
        svc.IsIPv4(ip_address) # True

## Propriétés

L'objet SF_String fournit les propriétés suivantes pour les scripts Basic :

Nom | Lecture seule | Description
--- | --- | ---
sfCR | Oui | Retour chariot : Chr(13)
sfCRLF | Oui | Retour chariot + saut de ligne : Chr(13) & Chr(10)
sfLF | Oui | Saut de ligne : Chr(10)
sfNEWLINE | Oui | Retour chariot + saut de ligne, qui peut être 1) Chr(13) & Chr(10) ou 2) saut de ligne : Chr(10) selon le système d'exploitation.
sfTAB | Oui | Tabulation horizontale : Chr(9)

Vous pouvez utiliser les propriétés ci-dessus pour identifier ou insérer les caractères correspondants dans les chaînes. Par exemple, le saut de ligne peut être remplacé par SF_String.sfLF.

Liste des méthodes dans le service String
Capitalize Count EndsWith Escape ExpandTabs FilterNotPrintable FindRegex HashStr HtmlEncode IsADate IsAlpha IsAlphaNum IsAscii IsDigit IsEmail | IsFileName IsHexDigit IsIBAN IsIPv4 IsLike IsLower IsPrintable IsRegex IsSheetName IsTitle IsUpper IsUrl IsWhitespace JustifyCenter JustifyLeft | JustifyRight Quote ReplaceChar ReplaceRegex ReplaceStr Represent Reverse SplitLines SplitNotQuoted StartsWith TrimExt Unescape Unquote Wrap

Le premier argument de la plupart des méthodes est la chaîne à considérer. Il est toujours passé par référence et laissé inchangé. Des méthodes telles que Capitalize, Escape, etc. renvoient une nouvelle chaîne après leur exécution.

Étant donné que Python dispose d'une prise en charge intégrée complète des chaînes, la plupart des méthodes du service String sont disponibles uniquement pour les scripts Basic. Les méthodes disponibles pour Basic et Python sont : HashStr, IsADate, IsEmail, IsFileName, IsIBAN, IsIPv4, IsLike, IsSheetName, IsUrl, SplitNotQuoted et Wrap.

## Capitalize

Met en majuscule le premier caractère de chaque mot dans la chaîne d'entrée.

### Syntaxe :

svc.Capitalize(inputstr: str): str

### Paramètres :

inputstr : la chaîne à mettre en majuscule.

### Exemple :

        Dim sName as String : sName = "john smith"
        Dim sCapitalizedName as String
        sCapitalizedName = SF_String.Capitalize(sName)
        MsgBox sCapitalizedName 'John Smith

## Count

Compte le nombre d'occurrences d'une sous-chaîne ou d'une expression régulière dans une chaîne.

### Syntaxe :

svc.Count(inputstr: str, substring: str, [isregex: bool], [casesensitive: bool]): int

### Paramètres :

inputstr : la chaîne d'entrée à examiner

substring : la sous-chaîne ou l'expression régulière à utiliser lors de la recherche

isregex : utilisez True si la sous-chaîne est une expression régulière (par défaut = False)

casesensitive : la recherche peut être sensible à la casse ou non (par défaut = False).

### Exemple :

        'Compte les occurrences de la sous-chaîne "ou" dans la chaîne d'entrée (renvoie 2)
        MsgBox SF_String.Count("Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "or", CaseSensitive := False)
        'Compte le nombre de mots avec uniquement des lettres minuscules (renvoie 7)
        MsgBox SF_String.Count("Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "\b[a-z]+\b", IsRegex := True, CaseSensitive := True)

Pour en savoir plus sur les expressions régulières, reportez-vous à la documentation de Python sur Opérations sur les expressions régulières.

## EndsWith

Renvoie True si une chaîne se termine par une sous-chaîne spécifiée.

La fonction renvoie False lorsque la chaîne ou la sous-chaîne a une longueur = 0 ou lorsque la sous-chaîne est plus longue que la chaîne.

### Syntaxe :

svc.EndsWith(inputstr: str, substring: str, [casesensitive: bool]): bool

### Paramètres :

inputstr : la chaîne à tester.

substring : la sous-chaîne à rechercher à la fin de inputstr.

casesensitive : la recherche peut être sensible à la casse ou non (par défaut = False).

### Exemple :

        ' Renvoie True car la méthode a été appelée avec la valeur par défaut CaseSensitive = False
        MsgBox SF_String.EndsWith("abcdefg", "EFG")
        'Renvoie False en raison du paramètre CaseSensitive
        MsgBox SF_String.EndsWith("abcdefg", "EFG", CaseSensitive := True)

## Escape

Convertit les sauts de ligne et les tabulations contenus dans la chaîne d'entrée en leur séquence d'échappement équivalente (\\, \n, \r, \t).

### Syntaxe :

svc.Escape(inputstr: str): str

### Paramètres :

inputstr : la chaîne à convertir.

### Exemple :

        'Renvoie la chaîne "abc\n\tdef\\n"
        MsgBox SF_String.Escape("abc" & Chr(10) & Chr(9) & "def\n")

## ExpandTabs

Remplace les caractères de tabulation Chr(9) par des espaces pour reproduire le comportement des taquets de tabulation.

Si un saut de ligne est trouvé, une nouvelle ligne est commencée et le compteur de caractères est réinitialisé.

### Syntaxe :

svc.ExpandTabs(inputstr: str, [tabsize: int]): str

### Paramètres :

inputstr : la chaîne à développer

tabsize : ce paramètre est utilisé pour déterminer les taquets de tabulation à l'aide de la formule : TabSize + 1, 2 * TabSize + 1 , ... N * TabSize + 1 (par défaut = 8)

### Exemple :

        Dim myText as String
        myText = "100" & SF_String.sfTAB & "200" & SF_String.sfTAB & "300" & SF_String.sfNEWLINE & _
                 "X"  & SF_String.sfTAB & "Y" & SF_String.sfTAB & "Z"
        MsgBox SF_String.ExpandTabs(myText)
        '100     200     300
        'X       Y       Z

## FilterNotPrintable

Remplace tous les caractères non imprimables de la chaîne d'entrée par un caractère donné.

### Syntaxe :

svc.FilterNotPrintable(inputstr: str, [replacedby: str]): str

### Paramètres :

inputstr : la chaîne à rechercher

replacedby : zéro, un ou plusieurs caractères qui remplaceront tous les caractères non imprimables dans inputstr (par défaut = "")

### Exemple :

        Dim LF : LF = Chr(10)
        Dim myText as String
        myText = "àén ΣlPµ" & LF & " Русский" & "\n"
        MsgBox SF_String.FilterNotPrintable(myText)
        ' "àén ΣlPµ Русский\n"

## FindRegex

Recherche dans une chaîne une sous-chaîne correspondant à une expression régulière donnée.

### Syntaxe :

svc.FindRegex(inputstr: str, regex: str, [start: int], [casesensitive: bool], [forward: bool]): str

### Paramètres :

inputstr : la chaîne à rechercher

regex : l'expression régulière

start : la position dans la chaîne où la recherche commencera. Ce paramètre est passé par référence, donc après l'exécution, la valeur de start pointera vers le premier caractère de la sous-chaîne trouvée. Si aucune sous-chaîne correspondante n'est trouvée, start sera défini sur 0.

casesensitive : la recherche peut être sensible à la casse ou non (par défaut = False).

forward : détermine la direction de la recherche. Si True, la recherche se fait en avant. Si False la recherche se fait en arrière (par défaut = True)

A la première itération, si forward = True, alors start doit être égal à 1, alors que si forward = False alors start doit être égal à Len(inputstr)

### Exemple :

        Dim lStart As Long : lStart = 1
        Dim result as String
        result = SF_String.FindRegex("abCcdefghHij", "C.*H", lStart, CaseSensitive := True)
        MsgBox lStart & ": " & result
        '3: CcdefghH

Dans l'exemple ci-dessus, la nouvelle valeur de lStart peut être utilisée pour continuer à rechercher la même chaîne d'entrée en définissant le paramètre Start sur lStart + Len(result) à la prochaine itération.

## HashStr

Les fonctions de hachage sont utilisées dans certains algorithmes de chiffrement, dans les signatures numériques, les codes d'authentification des messages, la détection des manipulations, les empreintes digitales, les sommes de contrôle (vérification de l'intégrité des messages), les tables de hachage, le stockage des mots de passe et bien plus encore.

La méthode HashStr renvoie le résultat d'une fonction de hachage appliquée sur une chaîne donnée et utilisant un algorithme spécifié, sous la forme d'une chaîne de chiffres hexadécimaux minuscules.

Les algorithmes de hachage pris en charge sont : MD5, SHA1, SHA224, SHA256, SHA384 et SHA512.

### Syntaxe :

svc.HashStr(inputstr: str, algorithm: str): str

### Paramètres :

inputstr : la chaîne à hacher. Elle est supposée être encodée en UTF-8. L'algorithme de hachage considérera la chaîne comme un flux d'octets.

algorithm : l'un des algorithmes pris en charge répertoriés ci-dessus, transmis sous forme de chaîne.

### Exemple :

##### En Basic :

        MsgBox SF_String.HashStr("œ∑¡™£¢∞§¶•ªº–≠œ∑´®†¥¨ˆøπ‘åß∂ƒ©˙∆˚¬", "MD5")
        ' c740ccc2e201df4b2e2b4aa086f35d8a

##### En Python

        svc = CreateScriptService("String")
        bas = CreateScriptService("Basic")
        a_string = "œ∑¡™£¢∞§¶•ªº–≠œ∑´®†¥¨ˆøπ‘åß∂ƒ©˙∆˚¬"
        hash_value = svc.HashStr(a_string, "MD5")
        bas.MsgBox(hash_value)
        # c740ccc2e201df4b2e2b4aa086f35d8a

## HtmlEncode

Encode la chaîne d'entrée dans les codes de caractères HTML, en remplaçant les caractères spéciaux par leurs homologues &.

Par exemple, le caractère é serait remplacé par &eacute; ou un code HTML numérique équivalent.

### Syntaxe :

svc.HtmlEncode(inputstr: str): str

### Paramètres :

inputstr : la chaîne à encoder.

### Exemple :

        MsgBox SF_String.HtmlEncode("<a href=""https://a.b.com"">From α to ω</a>")
        ' "&lt;a href=&quot;https://a.b.com&quot;&gt;From &#945; to &#969;&lt;/a&gt;"

## IsADate

Renvoie True si la chaîne d'entrée est une date valide selon un format de date spécifié.

### Syntaxe :

svc.IsADate(inputstr: str, [dateformat: str]): bool

### Paramètres :

inputstr : la chaîne à vérifier. Si vide, la méthode renvoie False

dateformat : format de date, sous forme de chaîne. Il peut s'agir de "AAAA-MM-JJ" (par défaut), "JJ-MM-AAAA" ou "MM-JJ-AAAA"

Le tiret (-) peut être remplacé par un point (.), une barre oblique (/) ou un espace.

Si le format n'est pas valide, la méthode renvoie False.

### Exemple :

##### En Basic :

        MsgBox SF_String.IsADate("2020-12-31", "YYYY-MM-DD") ' True

Cette méthode vérifie le format de la chaîne d'entrée sans effectuer de vérification spécifique du calendrier. Par conséquent, elle ne teste pas la chaîne d'entrée pour les années bissextiles ou les mois avec 30 ou 31 jours. Pour cela, reportez-vous à la fonction intégrée IsDate.

L'exemple ci-dessous montre la différence entre les méthodes IsADate (ScriptForge) et la fonction IsDate (intégrée).

        Dim myDate as String : myDate = "2020-02-30"
        MsgBox SF_String.IsADate(myDate, "YYYY-MM-DD") 'True
        MsgBox IsDate(myDate) ' False

##### En Python

        svc = CreateScriptService("String")
        s_date = "2020-12-31"
        result = svc.IsADate(s_date) # True

## IsAlpha

Renvoie True si tous les caractères de la chaîne sont alphabétiques.

Les caractères alphabétiques sont les caractères définis dans la Unicode Character Database comme Letter.

### Syntaxe :

svc.IsAlpha(inputstr: str): bool

### Paramètres :

inputstr : la chaîne à vérifier. Si vide, la méthode renvoie False

### Exemple :

        MsgBox SF_String.IsAlpha("àénΣlPµ") ' True
        MsgBox SF_String.IsAlpha("myVar3") ' False

## IsAlphaNum

Renvoie True si tous les caractères de la chaîne sont alphabétiques, numériques ou "_" (trait de soulignement). Le premier caractère ne doit pas être un chiffre.

### Syntaxe :

svc.IsAlphaNum(inputstr: str): bool

### Paramètres :

inputstr : la chaîne à vérifier. Si vide, la méthode renvoie False

### Exemple :

        MsgBox SF_String.IsAlphaNum("_ABC_123456_abcàénΣlPµ") ' True
        MsgBox SF_String.IsAlphaNum("123ABC") ' False

## IsAscii

Renvoie True si tous les caractères de la chaîne sont des caractères ASCII.

### Syntaxe :

svc.IsAscii(inputstr: str): bool

### Paramètres :

inputstr : la chaîne à vérifier. Si vide, la méthode renvoie False

### Exemple :

        MsgBox SF_String.IsAscii("a%?,25") ' True
        MsgBox SF_String.IsAscii("abcàénΣlPµ") ' False

## IsDigit

Renvoie True si tous les caractères de la chaîne sont des chiffres.

### Syntaxe :

svc.IsDigit(inputstr: str): bool

### Paramètres :

inputstr : la chaîne à vérifier. Si vide, la méthode renvoie False

### Exemple :

        MsgBox SF_String.IsDigit("123456") ' True
        MsgBox SF_String.IsDigit("_12a") ' False

## IsEmail

Renvoie True si la chaîne est une adresse e-mail valide.

### Syntaxe :

svc.IsEmail(inputstr: str): bool

### Paramètres :

inputstr : la chaîne à vérifier. Si vide, la méthode renvoie False

### Exemple :

##### En Basic :

        MsgBox SF_String.IsEmail("first.last@something.org") ' True
        MsgBox SF_String.IsEmail("first.last@something.com.br") ' True
        MsgBox SF_String.IsEmail("first.last@something.123") ' False

##### En Python

        svc = CreateScriptService("String")
        bas = CreateScriptService("Basic")
        bas.MsgBox(svc.IsEmail("first.last@something.org")) # True
        bas.MsgBox(svc.IsEmail("first.last@something.com.br")) # True
        bas.MsgBox(svc.IsEmail("first.last@something.123")) # False

## IsFileName

Renvoie True si la chaîne est un nom de fichier valide dans un système d'exploitation donné.

### Syntaxe :

svc.IsFileName(inputstr: str, [osname: str]): bool

### Paramètres :

inputstr : la chaîne à vérifier. Si vide, la méthode renvoie False

osname : le nom du système d'exploitation, sous forme de chaîne. Il peut s'agir de "WINDOWS", "LINUX", "MACOSX" ou "SOLARIS".

La valeur par défaut est le système d'exploitation actuel sur lequel le script s'exécute.

### Exemple :

##### En Basic :

        MsgBox SF_String.IsFileName("/home/user/Documents/a file name.odt", "LINUX") ' True
        MsgBox SF_String.IsFileName("C:\home\a file name.odt", "LINUX") ' False
        MsgBox SF_String.IsFileName("C:\home\a file name.odt", "WINDOWS") ' True

##### En Python

        svc = CreateScriptService("String")
        bas = CreateScriptService("Basic")
        bas.MsgBox(svc.IsFileName("/home/user/Documents/a file name.odt", "LINUX")) # True
        bas.MsgBox(svc.IsFileName(r"C:\home\a file name.odt", "LINUX")) # False
        bas.MsgBox(svc.IsFileName(r"C:\home\a file name.odt", "WINDOWS")) # True

## IsHexDigit

Renvoie True si tous les caractères de la chaîne sont des chiffres hexadécimaux.

### Syntaxe :

svc.IsHexDigit(inputstr: str): bool

### Paramètres :

inputstr : la chaîne à vérifier. Si vide, la méthode renvoie False

Les chiffres hexadécimaux peuvent être précédés de "0x" ou "&H".

### Exemple :

        MsgBox SF_String.IsHexDigit("&H00FF") ' True
        MsgBox SF_String.IsHexDigit("08AAFF10") ' True
        MsgBox SF_String.IsHexDigit("0x18LA22") ' False

## IsIBAN

Renvoie True si la chaîne est un numéro de compte bancaire international (IBAN) valide. La comparaison n'est pas sensible à la casse.

### Syntaxe :

svc.IsIBAN(inputstr: str): bool

### Paramètres :

inputstr : la chaîne à vérifier. Si vide, la méthode renvoie False

### Valeur de retour :

True si la chaîne contient un numéro IBAN valide.

### Exemple :

        ' Basic
        MsgBox SF_String.IsIBAN("BR15 0000 0000 0000 1093 2840 814 P2") ' True

        # Python
        result = svc.IsIBAN("BR15 0000 0000 0000 1093 2840 814 P2") # True

## IsIPv4

Renvoie True si la chaîne est une adresse IP(v4) valide.

### Syntaxe :

svc.IsIPv4(inputstr: str): bool

### Paramètres :

inputstr : la chaîne à vérifier. Si vide, la méthode renvoie False

### Exemple :

##### En Basic :

        MsgBox SF_String.IsIPv4("192.168.1.50") ' True
        MsgBox SF_String.IsIPv4("192.168.50") ' False
        MsgBox SF_String.IsIPv4("255.255.255.256") ' False

##### En Python

        svc = CreateScriptService("String")
        bas = CreateScriptService("Basic")
        bas.MsgBox(svc.IsIPv4("192.168.1.50")) # True
        bas.MsgBox(svc.IsIPv4("192.168.50")) # False
        bas.MsgBox(svc.IsIPv4("255.255.255.256")) # False

## IsLike

Renvoie True si toute la chaîne d'entrée correspond à un modèle donné contenant des caractères génériques.

### Syntaxe :

svc.IsLike(inputstr: str, pattern: str, [casesensitive: bool]): bool

### Paramètres :

inputstr : la chaîne à vérifier. Si vide, la méthode renvoie False

motif : le modèle sous forme de chaîne. Les jokers sont :

- "?" représente n'importe quel caractère unique ;

- "*" représente zéro, un ou plusieurs caractères.

casesensitive : la recherche peut être sensible à la casse ou non (par défaut = False).

### Exemple :

##### En Basic :

        MsgBox SF_String.IsLike("aAbB", "?A*") ' True
        MsgBox SF_String.IsLike("C:\a\b\c\f.odb", "?:*.*") ' True
        MsgBox SF_String.IsLike("name:host", "?*@?*") ' False
        MsgBox SF_String.IsLike("@host", "?*@?*") ' False

##### En Python

        svc = CreateScriptService("String")
        bas = CreateScriptService("Basic")
        bas.MsgBox(svc.IsLike("aAbB", "?A*")) # True
        bas.MsgBox(svc.IsLike(r"C:\a\b\c\f.odb", "?:*.*")) # True
        bas.MsgBox(svc.IsLike("name:host", "?*@?*")) # False
        bas.MsgBox(svc.IsLike("@host", "?*@?*")) # False

## IsLower

Renvoie True si tous les caractères de la chaîne sont en minuscules. Les caractères non alphabétiques sont ignorés.

### Syntaxe :

svc.IsLower(inputstr: str): bool

### Paramètres :

InputStr : la chaîne à vérifier. Si vide, la méthode renvoie False.

### Exemple :

        MsgBox SF_String.IsLower("abc'(-xy4z") ' True
        MsgBox SF_String.IsLower("1234") ' True
        MsgBox SF_String.IsLower("abcDefg") ' False

## IsPrintable

Renvoie True si tous les caractères de la chaîne sont imprimables.

### Syntaxe :

svc.IsPrintable(inputstr: str): bool

### Paramètres :

inputstr : la chaîne à vérifier. Si vide, la méthode renvoie False

### Exemple :

        MsgBox SF_String.IsPrintable("àén ΣlPµ Русский") ' True
        MsgBox SF_String.IsPrintable("First line." & Chr(10) & "Second Line.") ' False

## IsRegex

Renvoie True si toute la chaîne d'entrée correspond à une expression régulière donnée.

### Syntaxe :

svc.IsRegex(inputstr: str, regex: str, [casesensitive: bool]): bool

### Paramètres :

inputstr : la chaîne à vérifier. Si vide, la méthode renvoie False

regex : L'expression régulière. Si vide, la méthode renvoie False.

casesensitive : la recherche peut être sensible à la casse ou non (par défaut = False).

### Exemple :

            MsgBox SF_String.IsRegex("aAbB", "[A-Za-z]+") ' True
            MsgBox SF_String.IsRegex("John;100", "[A-Za-z]+;[0-9]+") ' True
            MsgBox SF_String.IsRegex("John;100;150", "[A-Za-z]+;[0-9]+") ' False

## IsSheetName

Renvoie True si la chaîne d'entrée est un nom de feuille Calc valide.

### Syntaxe :

svc.IsSheetName(inputstr: str): bool

### Paramètres :

inputstr : la chaîne à vérifier. Si vide, la méthode renvoie False

### Exemple :

##### En Basic :

        MsgBox SF_String.IsSheetName("1àbc + ""déf""") ' True
        MsgBox SF_String.IsSheetName("[MySheet]") ' False

##### En Python

        svc = CreateScriptService("String")
        bas = CreateScriptService("Basic")
        bas.MsgBox(svc.IsSheetName("1àbc + ""déf""")) # True
        bas.MsgBox(svc.IsSheetName("[MySheet]")) # False

Un nom de feuille ne doit pas contenir les caractères [ ] * ? : / \ ou le caractère ' (apostrophe) comme premier ou dernier caractère.

## IsTitle

Renvoie True si le premier caractère de chaque mot est en majuscule et les autres caractères sont en minuscules.

### Syntaxe :

svc.IsTitle(inputstr: str): bool

### Paramètres :

inputstr : la chaîne à vérifier. Si vide, la méthode renvoie False

### Exemple :

        MsgBox SF_String.IsTitle("This Is The Title Of My Book") ' True
        MsgBox SF_String.IsTitle("This is the Title of my Book") ' False
        MsgBox SF_String.IsTitle("Result Number 100") ' True

## IsUpper

Renvoie True si tous les caractères de la chaîne sont en majuscules. Les caractères non alphabétiques sont ignorés.

### Syntaxe :

svc.IsUpper(inputstr: str): bool

### Paramètres :

inputstr : la chaîne à vérifier. Si vide, la méthode renvoie False

### Exemple :

        MsgBox SF_String.IsUpper("ABC'(-XYZ") ' True
        MsgBox SF_String.IsUpper("A Title") ' False

## IsUrl

Renvoie True si la chaîne est une adresse URL absolue (Uniform Resource Locator) valide. Seuls les protocoles http, https et ftp sont pris en charge.

### Syntaxe :

svc.IsUrl(inputstr: str): bool

### Paramètres :

inputstr : la chaîne à vérifier. Si vide, la méthode renvoie False

### Exemple :

##### En Basic :

        MsgBox SF_String.IsUrl("http://foo.bar/?q=Test%20URL-encoded%20stuff") ' True
        MsgBox SF_String.IsUrl("www.somesite.org") ' False

##### En Python

        svc = CreateScriptService("String")
        bas = CreateScriptService("Basic")
        bas.MsgBox(svc.IsUrl("http://foo.bar/?q=Test%20URL-encoded%20stuff")) # True
        bas.MsgBox(svc.IsUrl("www.somesite.org")) # False

## IsWhitespace

Renvoie True si tous les caractères de la chaîne sont des espaces

### Syntaxe :

svc.IsWhitespace(inputstr: str): bool

### Paramètres :

inputstr : la chaîne à vérifier. Si vide, la méthode renvoie False

### Exemple :

        MsgBox SF_String.IsWhitespace("    ") ' True
        MsgBox SF_String.IsWhitespace(" " & Chr(9) & Chr(10)) ' True
        MsgBox SF_String.IsWhitespace("") ' False

## JustifyCenter

Renvoie la chaîne d'entrée justifiée au centre.

Les espaces blancs de début et de fin sont supprimés et les caractères restants sont complétés à gauche et à droite jusqu'à une length totale spécifiée avec le caractère padding.

### Syntaxe :

svc.JustifyCenter(inputstr: str, [length: int], [padding: str]): str

### Paramètres :

inputstr : la chaîne à justifier au centre. Si elle est vide, la méthode renvoie une chaîne vide.

length : la longueur de la chaîne résultante (par défaut = la longueur de la chaîne d'entrée).

Si la longueur spécifiée est plus courte que la chaîne d'entrée justifiée au centre, la chaîne renvoyée est tronquée.

padding : Le caractère unique à utiliser comme remplissage (par défaut = l'espace ASCII " ").

### Exemple :

        MsgBox SF_String.JustifyCenter("Title", Length := 11) ' "   Title   "
        MsgBox SF_String.JustifyCenter("    ABCDEF", Padding := "_") ' "__ABCDEF__"
        MsgBox SF_String.JustifyCenter("A Long Title", Length := 5) ' "ong T"

## JustifyLeft

Renvoie la chaîne d'entrée justifiée à gauche.

Les espaces blancs au début sont supprimés et les caractères restants sont complétés à droite jusqu'à une length totale spécifiée avec le caractère padding.

### Syntaxe :

svc.JustifyLeft(inputstr: str, [length: int], [padding: str]): str

### Paramètres :

inputstr : la chaîne à justifier à gauche. Si elle est vide, la méthode renvoie une chaîne vide.

length : la longueur de la chaîne résultante (par défaut = la longueur de la chaîne d'entrée).

Si la longueur spécifiée est plus courte que la chaîne d'entrée justifiée à gauche, la chaîne renvoyée est tronquée.

padding : Le caractère unique à utiliser comme remplissage (par défaut = l'espace ASCII " ").

### Exemple :

        MsgBox SF_String.JustifyLeft("Title", Length := 10) ' "Title     "
        MsgBox SF_String.JustifyLeft("    ABCDEF", Padding := "_") ' "ABCDEF____"
        MsgBox SF_String.JustifyLeft("A Long Title", Length := 5) ' "A Lon"

## JustifyRight

Renvoie la chaîne d'entrée justifiée à droite.

Les espaces blancs au début sont supprimés et les caractères restants sont complétés à gauche jusqu'à une length totale spécifiée avec le caractère padding.

### Syntaxe :

svc.JustifyRight(inputstr: str, [length: int], [padding: str]): str

### Paramètres :

inputstr : la chaîne à justifier à droite. Si elle est vide, la méthode renvoie une chaîne vide.

length : la longueur de la chaîne résultante (par défaut = la longueur de la chaîne d'entrée).

Si la longueur spécifiée est plus courte que la chaîne d'entrée justifiée à droite, la chaîne renvoyée est tronquée.

padding : Le caractère unique à utiliser comme remplissage (par défaut = l'espace ASCII " ").

### Exemple :

        MsgBox SF_String.JustifyRight("Title", Length := 10) ' "     Title"
        MsgBox SF_String.JustifyRight("  ABCDEF  ", Padding := "_") ' "____ABCDEF"
        MsgBox SF_String.JustifyRight("A Long Title", Length := 5) ' "Title"

## Quote

Renvoie la chaîne d'entrée entre guillemets simples ou doubles. Les guillemets existants restent inchangés, y compris les guillemets de début et/ou de fin.

### Syntaxe :

svc.Quote(inputstr: str, [quotechar: str]): str

### Paramètres :

inputstr : la chaîne à mettre entre guillemets.

quotechar : soit le guillemet simple (') ou double ("") (par défaut).

### Exemple :

        MsgBox SF_String.Quote("Text Value")
        ' "Text Value"
        MsgBox SF_String.Quote("Book Title: ""The Arabian Nights""", "'")
        ' 'Book Title: "The Arabian Nights"'

Cette méthode peut être utile lors de la préparation d'un champ de chaîne à stocker dans un fichier de type csv, qui nécessite que les valeurs de texte soient entourées de guillemets simples ou doubles.

## ReplaceChar

Remplace toutes les occurrences des caractères spécifiés dans le paramètre Before par les caractères correspondants spécifiés dans After.

Si la longueur de Before est supérieure à la longueur de After, les caractères résiduels dans Before sont remplacés par le dernier caractère dans After.

### Syntaxe :

svc.ReplaceChar(inputstr: str, before: str, after: str): str

### Paramètres :

inputstr : la chaîne d'entrée sur laquelle les remplacements auront lieu.

before : une chaîne avec les caractères qui seront recherchés dans la chaîne d'entrée pour le remplacement.

after : une chaîne avec les nouveaux caractères qui remplaceront ceux définis dans before.

### Exemple :

        ' Remplace les caractères accentués
        MsgBox SF_String.ReplaceChar("Protégez votre vie privée", "àâãçèéêëîïôöûüýÿ", "aaaceeeeiioouuyy")
        ' "Protegez votre vie privee"
        MsgBox SF_String.ReplaceChar("Protégez votre vie privée", "àâãçèéêëîïôöûüýÿ", "")
        ' "Protgez votre vie prive"
        MsgBox SF_String.ReplaceChar("àâãçèéêëîïôöûüýÿ", "àâãçèéêëîïôöûüýÿ", "aaaceeeeiioouuyy")
        ' "aaaceeeeiioouuyy"

Le service SF_String fournit des constantes publiques utiles pour les jeux de caractères latins, comme illustré dans l'exemple ci-dessous :

        MsgBox SF_String.ReplaceChar("Protégez votre vie privée", SF_String.CHARSWITHACCENT, SF_String.CHARSWITHOUTACCENT)
        ' "Protegez votre vie privee"

## ReplaceRegex

Remplace toutes les occurrences d'une expression régulière donnée par une nouvelle chaîne.

### Syntaxe :

svc.ReplaceRegex(inputstr: str, regex: str, newstr: str, [casesensitive: bool]): str

### Paramètres :

inputstr : la chaîne d'entrée sur laquelle les remplacements auront lieu.

regex : l'expression régulière.

newstr : la chaîne de remplacement.

casesensitive : la recherche peut être sensible à la casse ou non (par défaut = False).

### Exemple :

        MsgBox SF_String.ReplaceRegex("Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "[a-z]", "x", CaseSensitive := True)
        " "Lxxxx xxxxx xxxxx xxx xxxx, xxxxxxxxxxx xxxxxxxxxx xxxx." (chaque lettre minuscule est remplacée par "x")
        MsgBox SF_String.ReplaceRegex("Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "\b[a-z]+\b", "x", CaseSensitive := False)
        ' "x x x x x, x x x." (chaque mot est remplacé par "x")

## ReplaceStr

Remplace dans une chaîne certaines ou toutes les occurrences d'une matrice de chaînes par une matrice de nouvelles chaînes.

### Syntaxe :

svc.ReplaceStr(inputstr: str, oldstr: str, newstr: str, [occurrences: int], [casesensitive: bool]): str

### Paramètres :

inputstr : la chaîne d'entrée sur laquelle les remplacements auront lieu.

oldstr : une chaîne unique ou une matrice de chaînes. Les chaînes de longueur nulle sont ignorées.

newstr : la chaîne de remplacement ou la matrice de chaînes de remplacement.

Si oldstr est une matrice, chaque occurrence de l'un des éléments de oldstr est remplacée par newstr.

Si oldstr et newstr sont des matrices, les remplacements se produisent un par un jusqu'à UBound(newstr).

Si oldstr a plus d'entrées que newstr, alors les éléments résiduels de oldstr sont remplacés par le dernier élément de newstr .

occurrences : nombre maximum de remplacements. La valeur par défaut est 0, ce qui signifie que toutes les occurrences seront remplacées.

Lorsque oldstr est une matrice, le paramètre occurrence est calculé séparément pour chaque élément de la matrice.

casesensitive : la recherche peut être sensible à la casse ou non (par défaut = False).

### Exemple :

        MsgBox SF_String.ReplaceStr("100 xxx 200 yyy", Array("xxx", "yyy"), Array("(1)", "(2)"), CaseSensitive := False)
        ' "100 (1) 200 (2)"
        MsgBox SF_String.ReplaceStr("abCcdefghHij", Array("c", "h"), Array("Y", "Z"), CaseSensitive := False)
        ' "abYYdefgZZij"

## Represent

Renvoie une chaîne avec une représentation lisible de l'argument, tronquée à une longueur donnée. Ceci est utile principalement à des fins de débogage ou de journalisation.

Si le paramètre anyvalue est un objet, il sera entouré de crochets "[" et "]".

Dans les chaînes, les tabulations et les sauts de ligne sont remplacés par \t, \n ou \r.

Si la longueur finale dépasse le paramètre maxlength, la dernière partie de la chaîne est remplacée par " ... (N)" où N est la longueur totale de la chaîne d'origine avant troncature.

### Syntaxe :

svc.Represent(anyvalue: any, [maxlength: int]): str

### Paramètres :

anyvalue : la valeur d'entrée à représenter. Il peut s'agir de n'importe quelle valeur, comme une chaîne, un tableau, un objet Basic, un objet UNO, etc.

maxlength : La longueur maximale de la chaîne résultante. La valeur par défaut est 0, ce qui signifie qu'il n'y a aucune limite à la longueur de la représentation résultante.

### Exemple :

        MsgBox SF_String.Represent("this is a usual string") ' "this is a usual string"
        MsgBox SF_String.Represent("this is a usual string", 15) ' "this i ... (22)"
        MsgBox SF_String.Represent("this is a" & Chr(10) & " 2-lines string") ' "this is a\n 2-lines string"
        MsgBox SF_String.Represent(Empty) ' "[EMPTY]"
        MsgBox SF_String.Represent(Null) ' "[NULL]"
        MsgBox SF_String.Represent(Pi) ' "3.142"
        MsgBox SF_String.Represent(CreateUnoService("com.sun.star.util.PathSettings")) ' "[com.sun.star.comp.framework.PathSettings]"

Notez que la représentation des types de données tels que les matrices et les instances d'objets ScriptForge.Dictionary incluent à la fois le type de données et leurs valeurs :

        ' Un exemple avec une matrice intégrée en Basic
        MsgBox SF_String.Represent(Array(1, 2, "Text" & Chr(9) & "here"))
        ' "[ARRAY] (0:2) (1, 2, Text\there)"
        ' Un exemple avec une matrice ScriptForge
        Dim aValues as Variant
        aValues = SF_Array.RangeInit(1, 5)
        MsgBox SF_String.Represent(aValues)
        ' "[ARRAY] (0:4) (1.0, 2.0, 3.0, 4.0, 5.0)"
        ' Un exemple avec un dictionnaire ScriptForge
        Dim myDict As Variant : myDict = CreateScriptService("Dictionary")
        myDict.Add("A", 1) : myDict.Add("B", 2)
        MsgBox SF_String.Represent(myDict)
        ' "[Dictionary] ("A":1, "B":2)"

## Reverse

Renvoie la chaîne d'entrée dans l'ordre inversé.

Cette méthode est équivalente à la StrReverse fonction de base intégrée.

Pour utiliser la fonction StrReverse, l'instruction Option VBASupport 1 doit être présente dans le module.

### Syntaxe :

svc.Reverse(inputstr: str): str

### Paramètres :

inputstr : la chaîne à inverser.

### Exemple :

        MsgBox SF_String.Reverse("abcdefghij") ' "jihgfedcba"

## SplitLines

Renvoie une matrice de chaînes de base zéro avec les lignes de la chaîne d'entrée. Chaque élément de la matrice est obtenu en divisant la chaîne d'entrée en caractères de nouvelle ligne.

### Syntaxe :

svc.SplitLines(inputstr: str, [keepbreaks: int]): str[0..*]

### Paramètres :

inputstr : la chaîne à diviser.

keepbreaks : lorsque True, les sauts de ligne sont conservés dans le tableau de sortie (par défaut = False).

### Exemple :

        Dim a as Variant
        a = SF_String.SplitLines("Line1" & Chr(10) & "Line2" & Chr(13) & "Line3")
        ' a = Array("Line1", "Line2", "Line3")
        a = SF_String.SplitLines("Line1" & Chr(10) & "Line2" & Chr(13) & "Line3" & Chr(10))
        ' a = Array("Line1", "Line2", "Line3", "")
        a = SF_String.SplitLines("Line1" & Chr(10) & "Line2" & Chr(13) & "Line3" & Chr(10), KeepBreaks := True)
        ' a = Array("Line1\n", "Line2\r", "Line3\n", "")

## SplitNotQuoted

Divise une chaîne en une matrice d'éléments à l'aide d'un délimiteur spécifié.

Si une sous-chaîne entre guillemets contient un délimiteur, celui-ci est ignoré. Ceci est utile lors de l'analyse d'enregistrements de type CSV contenant des chaînes entre guillemets.

### Syntaxe :

svc.SplitNotQuoted(inputstr: str, [delimiter: str], [occurrences: int], [quotechar: str]): str[0..*]

### Paramètres :

inputstr : la chaîne à diviser.

delimiter : Une chaîne d'un ou plusieurs caractères qui sera utilisée comme délimiteur. Le délimiteur par défaut est le caractère espace ASCII " ".

occurrences : le nombre maximum de sous-chaînes à renvoyer. La valeur par défaut est 0, ce qui signifie qu'il n'y a pas de limite au nombre de chaînes renvoyées.

quotechar : soit le guillemet simple (') ou double (").

### Exemple :

##### En Basic :

        arr1 = SF_String.SplitNotQuoted("abc def ghi")
        ' arr1 = Array("abc", "def", "ghi")
        arr2 = SF_String.SplitNotQuoted("abc,""def,ghi""", ",")
        ' arr2 = Array("abc", """def,ghi""")
        arr3 = SF_String.SplitNotQuoted("abc,""def\"",ghi""", ",")
         ' arr3 = Array("abc", """def\"",ghi""")
        arr4 = SF_String.SplitNotQuoted("abc,""def\"",ghi"""",", ",")
        ' arr4 = Array("abc", """def\"",ghi""", "")

##### En Python

        svc = CreateScriptService("String")
        arr1 = svc.SplitNotQuoted('abc def ghi')
        # arr1 = ('abc', 'def', 'ghi')
        arr2 = svc.SplitNotQuoted('abc,"def,ghi"', ",")
        # arr2 = ('abc', '"def,ghi"')
        arr3 = svc.SplitNotQuoted(r'abc,"def\",ghi"', ",")
        # arr3 = ('abc', '"def\\",ghi"')
        arr4 = svc.SplitNotQuoted(r'abc,"def\",ghi"",', ",")
        # arr4 = ('abc', '"def\\",ghi""', '')

Méfiez-vous des différences entre Basic et Python lors de la représentation de chaînes. Par exemple, en Basic, deux caractères "" à l'intérieur d'une chaîne sont interprétés comme un seul caractère ". En Python, les chaînes entourées de guillemets simples peuvent contenir des caractères " sans avoir à les doubler.

## StartsWith

Renvoie True si les premiers caractères d'une chaîne sont identiques à une sous-chaîne donnée.

Cette méthode renvoie False si la chaîne d'entrée ou la sous-chaîne a une longueur = 0 ou lorsque la sous-chaîne est plus longue que la chaîne d'entrée.

### Syntaxe :

svc.StartsWith(inputstr: str, substring: str, [casesensitive: bool]): bool

### Paramètres :

inputstr : la chaîne à tester.

substring : la sous-chaîne à rechercher au début de inputstr.

casesensitive : la recherche peut être sensible à la casse ou non (par défaut = False).

### Exemple :

        MsgBox SF_String.StartsWith("abcdefg", "ABC") 'True
        MsgBox SF_String.StartsWith("abcdefg", "ABC", CaseSensitive := True) 'False

## TrimExt

Renvoie la chaîne d'entrée sans ses espaces de début et de fin.

### Syntaxe :

svc.TrimExt(inputstr: str): str

### Paramètres :

inputstr : la chaîne à couper.

### Exemple :

        MsgBox SF_String.TrimExt(" Some text.  ") ' "Some text."
        MsgBox SF_String.TrimExt("   ABCDEF" & Chr(9) & Chr(10) & Chr(13) & " ") ' "ABCDEF"

## Unescape

Convertit toute séquence échappée (\\, \n, \r, \t) dans la chaîne d'entrée en son caractère ASCII correspondant.

### Syntaxe :

svc.Unescape(inputstr: str): str

### Paramètres :

inputstr : la chaîne à convertir.

### Exemple :

        MsgBox SF_String.Unescape("abc\n\tdef\\n")
        ' "abc" & Chr(10) & Chr(9) & "def\n"

## Unquote

Supprime les guillemets simples ou doubles entourant la chaîne d'entrée.

Ceci est utile lors de l'analyse d'enregistrements de type CSV contenant des chaînes entre guillemets.

### Syntaxe :

svc.Unquote(inputstr: str, [quotechar: str]): str

### Paramètres :

inputstr : la chaîne dont les guillemets doivent être supprimés.

quotechar : soit le guillemet simple (') ou double ("") (par défaut).

### Exemple :

        Dim s as String
        ' s = "Du texte" (sans guillemets)
        s = SF_String.Unquote("""Some text""")
        ' La chaîne ci-dessous n'a pas de guillemets, elle reste donc inchangée
        ' s = "Du texte" (inchangé)
        s = SF_String.Unquote("Some text")
        ' Les guillemets à l'intérieur de la chaîne ne sont pas supprimés
        ' s = "The ""true"" meaning" (inchangé)
        s = SF_String.Unquote("The ""true"" meaning")

## Wrap

Convertit la chaîne d'entrée en une matrice de sous-chaînes afin que chaque élément du tableau contienne au plus un nombre donné de caractères.

En pratique, cette méthode renvoie une matrice de lignes de sortie de base zéro, sans nouvelles lignes à la fin, à l'exception des sauts de ligne préexistants.

Les onglets sont développés à l'aide de la même procédure effectuée par la méthode ExpandTabs.

Les sauts de ligne symboliques sont remplacés par leurs caractères ASCII équivalents.

Si la sortie encapsulée n'a pas de contenu, la matrice renvoyée est vide.

### Syntaxe :

svc.Wrap(inputstr: str, [width: int], [tabsize: int]): str

### Paramètres :

inputstr : la chaîne à envelopper.

width : le nombre maximum de caractères dans chaque ligne (par défaut = 70).

tabsize : avant d'envelopper le texte, les caractères TAB Chr(9) existants sont remplacés par des espaces. L'argument tabsize définit les arrêts de tabulation à TabSize + 1, 2 * TabSize + 1 , ... N * TabSize + 1 (par défaut = 8).

### Exemple :

##### En Basic :

        a = "Neque porro quisquam est qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit..."
        b = SF_String.Wrap(a, 20)
        ' Array("Neque porro ", "quisquam est qui ", "dolorem ipsum quia ", "dolor sit amet, ", "consectetur, ", "adipisci velit...")

##### En Python

        a = "Neque porro quisquam est qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit..."
        b = svc.Wrap(a, 20)
        # ('Neque porro ', 'quisquam est qui ', 'dolorem ipsum quia ', 'dolor sit amet, ', 'consectetur, ', 'adipisci velit...')

Toutes les routines ou identifiants de base ScriptForge qui sont préfixés par un caractère de soulignement "_" sont réservés à un usage interne. Ils ne sont pas destinés à être utilisés dans des macros de base ou des scripts Python.

Rubriques connexes

ScriptForge. Service Array

Fonction String