logo
Free, unlimited AI code reviews that run on commit
git-lrc git-lrc GitHub Install Now We'd appreciate a star git-lrc - Free, unlimited AI code reviews that run on commit | Product Hunt git-lrc - Free, unlimited AI code reviews that run on commit | Product Hunt

string - String processing functions.

Data Types

direction() = leading | trailing

       grapheme_cluster() = char() | [char()]

              A user-perceived character, consisting of one or more codepoints.

Description

       This module provides functions for string processing.

       A  string  in  this  module is represented by unicode:chardata(), that is, a list of codepoints, binaries
       with UTF-8-encoded codepoints (UTF-8binaries), or a mix of the two.

       "abcd"               is a valid string
       <<"abcd">>           is a valid string
       ["abcd"]             is a valid string
       <<"abc..åäö"/utf8>>  is a valid string
       <<"abc..åäö">>       is NOT a valid string,
                            but a binary with Latin-1-encoded codepoints
       [<<"abc">>, "..åäö"] is a valid string
       [atom]               is NOT a valid string

       This module operates on grapheme clusters. A graphemecluster is a user-perceived character, which can be
       represented by several codepoints.

       "å"  [229] or [97, 778]
       "e̊"  [101, 778]

       The string length of "ß↑e̊" is 3, even though it is represented by the codepoints  [223,8593,101,778]  or
       the UTF-8 binary <<195,159,226,134,145,101,204,138>>.

       Grapheme  clusters  for  codepoints of class prepend and non-modern (or decomposed) Hangul is not handled
       for performance reasons in find/3, replace/3, split/2, split/2 and trim/3.

       Splitting and appending strings is to be done on grapheme clusters borders. There is no verification that
       the results of appending strings are valid or normalized.

       Most  of  the  functions  expect  all  input  to  be  normalized   to   one   form,   see   for   example
       unicode:characters_to_nfc_list/1.

       Language or locale specific handling of input is not considered in any function.

       The functions can crash for non-valid input strings. For example, the functions expect UTF-8 binaries but
       not all functions verify that all binaries are encoded correctly.

       Unless  otherwise  specified  the  return value type is the same as the input type. That is, binary input
       returns binary output, list input returns a list output, and mixed input can return a mixed output.

       1> string:trim("  sarah  ").
       "sarah"
       2> string:trim(<<"  sarah  ">>).
       <<"sarah">>
       3> string:lexemes("foo bar", " ").
       ["foo","bar"]
       4> string:lexemes(<<"foo bar">>, " ").
       [<<"foo">>,<<"bar">>]

       This module has been reworked in Erlang/OTP 20 to  handle  unicode:chardata()  and  operate  on  grapheme
       clusters.  The  oldfunctions that only work on Latin-1 lists as input are still available but should not
       be used, they will be deprecated in a future release.

Exports

centre(String,Number)->Centeredcentre(String,Number,Character)->Centered

              Types:

                 String = Centered = string()
                 Number = integer() >= 0
                 Character = char()

              Returns a string, where String is centered in the string and surrounded by  blanks  or  Character.
              The resulting string has length Number.

              This function is obsolete. Use pad/3.

       chars(Character,Number)->Stringchars(Character,Number,Tail)->String

              Types:

                 Character = char()
                 Number = integer() >= 0
                 Tail = String = string()

              Returns  a  string  consisting of Number characters Character. Optionally, the string can end with
              string Tail.

              This function is obsolete. Use lists:duplicate/2.

       chr(String,Character)->Index

              Types:

                 String = string()
                 Character = char()
                 Index = integer() >= 0

              Returns the index of the first occurrence of Character in String. Returns 0 if Character does  not
              occur.

              This function is obsolete. Use find/2.

       concat(String1,String2)->String3

              Types:

                 String1 = String2 = String3 = string()

              Concatenates String1 and String2 to form a new string String3, which is returned.

              This   function   is   obsolete.   Use   [String1,String2]   as   Data   argument,   and   call
              unicode:characters_to_list/2 or unicode:characters_to_binary/2 to flatten the output.

       copies(String,Number)->Copies

              Types:

                 String = Copies = string()
                 Number = integer() >= 0

              Returns a string containing String repeated Number times.

              This function is obsolete. Use lists:duplicate/2.

       cspan(String,Chars)->Length

              Types:

                 String = Chars = string()
                 Length = integer() >= 0

              Returns the length of the maximum initial segment of String, which consists entirely of characters
              not from Chars.

              This function is obsolete. Use take/3.

              Example:

              > string:cspan("\t    abcdef", " \t").
              0

       join(StringList,Separator)->String

              Types:

                 StringList = [string()]
                 Separator = String = string()

              Returns a string with the elements of StringList separated by the string in Separator.

              This function is obsolete. Use lists:join/2.

              Example:

              > join(["one", "two", "three"], ", ").
              "one, two, three"

       left(String,Number)->Leftleft(String,Number,Character)->Left

              Types:

                 String = Left = string()
                 Number = integer() >= 0
                 Character = char()

              Returns String with the length adjusted in accordance with Number. The left margin  is  fixed.  If
              length(String) < Number, then String is padded with blanks or Characters.

              This function is obsolete. Use pad/2 or pad/3.

              Example:

              > string:left("Hello",10,$.).
              "Hello....."

       len(String)->Length

              Types:

                 String = string()
                 Length = integer() >= 0

              Returns the number of characters in String.

              This function is obsolete. Use length/1.

       rchr(String,Character)->Index

              Types:

                 String = string()
                 Character = char()
                 Index = integer() >= 0

              Returns  the  index of the last occurrence of Character in String. Returns 0 if Character does not
              occur.

              This function is obsolete. Use find/3.

       right(String,Number)->Rightright(String,Number,Character)->Right

              Types:

                 String = Right = string()
                 Number = integer() >= 0
                 Character = char()

              Returns String with the length adjusted in accordance with Number. The right margin is  fixed.  If
              the length of (String) < Number, then String is padded with blanks or Characters.

              This function is obsolete. Use pad/3.

              Example:

              > string:right("Hello", 10, $.).
              ".....Hello"

       rstr(String,SubString)->Index

              Types:

                 String = SubString = string()
                 Index = integer() >= 0

              Returns  the  position  where  the  last  occurrence  of  SubString begins in String. Returns 0 if
              SubString does not exist in String.

              This function is obsolete. Use find/3.

              Example:

              > string:rstr(" Hello Hello World World ", "Hello World").
              8

       span(String,Chars)->Length

              Types:

                 String = Chars = string()
                 Length = integer() >= 0

              Returns the length of the maximum initial segment of String, which consists entirely of characters
              from Chars.

              This function is obsolete. Use take/2.

              Example:

              > string:span("\t    abcdef", " \t").
              5

       str(String,SubString)->Index

              Types:

                 String = SubString = string()
                 Index = integer() >= 0

              Returns the position where the first occurrence of  SubString  begins  in  String.  Returns  0  if
              SubString does not exist in String.

              This function is obsolete. Use find/2.

              Example:

              > string:str(" Hello Hello World World ", "Hello World").
              8

       strip(String::string())->string()strip(String,Direction)->Strippedstrip(String,Direction,Character)->Stripped

              Types:

                 String = Stripped = string()
                 Direction = left | right | both
                 Character = char()

              Returns  a  string,  where leading or trailing, or both, blanks or a number of Character have been
              removed. Direction, which can be left, right, or both, indicates from which direction  blanks  are
              to be removed. strip/1 is equivalent to strip(String,both).

              This function is obsolete. Use trim/3.

              Example:

              > string:strip("...Hello.....", both, $.).
              "Hello"

       sub_string(String,Start)->SubStringsub_string(String,Start,Stop)->SubString

              Types:

                 String = SubString = string()
                 Start = Stop = integer() >= 1

              Returns  a  substring  of  String,  starting at position Start to the end of the string, or to and
              including position Stop.

              This function is obsolete. Use slice/3.

              Example:

              sub_string("Hello World", 4, 8).
              "lo Wo"

       substr(String,Start)->SubStringsubstr(String,Start,Length)->SubString

              Types:

                 String = SubString = string()
                 Start = integer() >= 1
                 Length = integer() >= 0

              Returns a substring of String, starting at position Start, and ending at the end of the string  or
              at length Length.

              This function is obsolete. Use slice/3.

              Example:

              > substr("Hello World", 4, 5).
              "lo Wo"

       sub_word(String,Number)->Wordsub_word(String,Number,Character)->Word

              Types:

                 String = Word = string()
                 Number = integer()
                 Character = char()

              Returns the word in position Number of String. Words are separated by blanks or Characters.

              This function is obsolete. Use nth_lexeme/3.

              Example:

              > string:sub_word(" Hello old boy !",3,$o).
              "ld b"

       to_lower(String)->Resultto_lower(Char)->CharResultto_upper(String)->Resultto_upper(Char)->CharResult

              Types:

                 String = Result = io_lib:latin1_string()
                 Char = CharResult = char()

              The  specified  string  or character is case-converted. Notice that the supported character set is
              ISO/IEC 8859-1 (also called Latin 1); all values outside this set are unchanged

              This function is obsolete use lowercase/1, uppercase/1, titlecase/1 or casefold/1.

       tokens(String,SeparatorList)->Tokens

              Types:

                 String = SeparatorList = string()
                 Tokens = [Token :: nonempty_string()]

              Returns a list of tokens in String, separated by the characters in SeparatorList.

              Example:

              > tokens("abc defxxghix jkl", "x ").
              ["abc", "def", "ghi", "jkl"]

              Notice that, as shown in this example, two or more adjacent separator  characters  in  String  are
              treated as one. That is, there are no empty strings in the resulting list of tokens.

              This function is obsolete. Use lexemes/2.

       words(String)->Countwords(String,Character)->Count

              Types:

                 String = string()
                 Character = char()
                 Count = integer() >= 1

              Returns the number of words in String, separated by blanks or Character.

              This function is obsolete. Use lexemes/2.

              Example:

              > words(" Hello old boy!", $o).
              4

Name

       string - String processing functions.

Notes

       Some  of  the  general  string  functions  can seem to overlap each other. The reason is that this string
       package is the combination of two earlier packages and all functions of both packages have been retained.

Ericsson AB                                        stdlib 3.17                                      string(3erl)

Obsolete Api Functions

       Here follows the function of the old API. These functions only work on a list of Latin-1 characters.

   Note:
       The  functions are kept for backward compatibility, but are not recommended. They will be deprecated in a
       future release.

       Any undocumented functions in string are not to be used.

See Also