Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-02 14:48:21 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2
zeek/doc/scripts/base/bif/strings.bif.zeek.rst
Tim Wojtulewicz ded98cd373 Copy docs into Zeek repo directly 
This is based on commit 2731def9159247e6da8a3191783c89683363689c from the
zeek-docs repo.
2025-09-26 02:58:29 +00:00

1011 lines
37 KiB
ReStructuredText
Raw Permalink Blame History

:tocdepth: 3
base/bif/strings.bif.zeek
=========================
.. zeek:namespace:: GLOBAL
Definitions of built-in functions related to string processing and
manipulation.
:Namespace: GLOBAL
Summary
~~~~~~~
Functions
#########
====================================================== ==========================================================================================================
:zeek:id:`clean`: :zeek:type:`function` Replaces non-printable characters in a string with escaped sequences.
:zeek:id:`count_substr`: :zeek:type:`function` Returns the number of times a substring occurs within a string
:zeek:id:`edit`: :zeek:type:`function` Returns an edited version of a string that applies a special
"backspace character" (usually ``\x08`` for backspace or ``\x7f`` for DEL).
:zeek:id:`ends_with`: :zeek:type:`function` Returns whether a string ends with a substring.
:zeek:id:`escape_string`: :zeek:type:`function` Replaces non-printable characters in a string with escaped sequences.
:zeek:id:`find_all`: :zeek:type:`function` Finds all occurrences of a pattern in a string.
:zeek:id:`find_all_ordered`: :zeek:type:`function` Finds all occurrences of a pattern in a string.
:zeek:id:`find_first`: :zeek:type:`function` Finds the first occurrence of a pattern in a string.
:zeek:id:`find_last`: :zeek:type:`function` Finds the last occurrence of a pattern in a string.
:zeek:id:`find_str`: :zeek:type:`function` Finds a string within another string, starting from the beginning.
:zeek:id:`gsub`: :zeek:type:`function` Substitutes a given replacement string for all occurrences of a pattern
in a given string.
:zeek:id:`hexdump`: :zeek:type:`function` Returns a hex dump for given input data.
:zeek:id:`is_alnum`: :zeek:type:`function` Returns whether a string consists entirely of alphanumeric characters.
:zeek:id:`is_alpha`: :zeek:type:`function` Returns whether a string consists entirely of alphabetic characters.
:zeek:id:`is_ascii`: :zeek:type:`function` Determines whether a given string contains only ASCII characters.
:zeek:id:`is_num`: :zeek:type:`function` Returns whether a string consists entirely of digits.
:zeek:id:`join_string_set`: :zeek:type:`function` Joins all values in the given set of strings with a separator placed
between each element.
:zeek:id:`join_string_vec`: :zeek:type:`function` Joins all values in the given vector of strings with a separator placed
between each element.
:zeek:id:`levenshtein_distance`: :zeek:type:`function` Calculates the Levenshtein distance between the two strings.
:zeek:id:`ljust`: :zeek:type:`function` Returns a left-justified version of the string, padded to a specific length
with a specified character.
:zeek:id:`lstrip`: :zeek:type:`function` Removes all combinations of characters in the *chars* argument
starting at the beginning of the string until first mismatch.
:zeek:id:`remove_prefix`: :zeek:type:`function` Similar to lstrip(), except does the removal repeatedly if the pattern repeats at the start of the string.
:zeek:id:`remove_suffix`: :zeek:type:`function` Similar to rstrip(), except does the removal repeatedly if the pattern repeats at the end of the string.
:zeek:id:`reverse`: :zeek:type:`function` Returns a reversed copy of the string
:zeek:id:`rfind_str`: :zeek:type:`function` The same as :zeek:see:`find_str`, but returns the highest index matching
the substring instead of the smallest.
:zeek:id:`rjust`: :zeek:type:`function` Returns a right-justified version of the string, padded to a specific length
with a specified character.
:zeek:id:`rstrip`: :zeek:type:`function` Removes all combinations of characters in the *chars* argument
starting at the end of the string until first mismatch.
:zeek:id:`safe_shell_quote`: :zeek:type:`function` Takes a string and escapes characters that would allow execution of
commands at the shell level.
:zeek:id:`split_string`: :zeek:type:`function` Splits a string into an array of strings according to a pattern.
:zeek:id:`split_string1`: :zeek:type:`function` Splits a string *once* into a two-element array of strings according to a
pattern.
:zeek:id:`split_string_all`: :zeek:type:`function` Splits a string into an array of strings according to a pattern.
:zeek:id:`split_string_n`: :zeek:type:`function` Splits a string a given number of times into an array of strings according
to a pattern.
:zeek:id:`starts_with`: :zeek:type:`function` Returns whether a string starts with a substring.
:zeek:id:`str_smith_waterman`: :zeek:type:`function` Uses the Smith-Waterman algorithm to find similar/overlapping substrings.
:zeek:id:`str_split_indices`: :zeek:type:`function` Splits a string into substrings with the help of an index vector of cutting
points.
:zeek:id:`strcmp`: :zeek:type:`function` Lexicographically compares two strings.
:zeek:id:`string_cat`: :zeek:type:`function` Concatenates all arguments into a single string.
:zeek:id:`string_fill`: :zeek:type:`function` Generates a string of a given size and fills it with repetitions of a source
string.
:zeek:id:`string_to_ascii_hex`: :zeek:type:`function` Returns an ASCII hexadecimal representation of a string.
:zeek:id:`strip`: :zeek:type:`function` Strips whitespace at both ends of a string.
:zeek:id:`strstr`: :zeek:type:`function` Locates the first occurrence of one string in another.
:zeek:id:`sub`: :zeek:type:`function` Substitutes a given replacement string for the first occurrence of a pattern
in a given string.
:zeek:id:`sub_bytes`: :zeek:type:`function` Get a substring from a string, given a starting position and length.
:zeek:id:`subst_string`: :zeek:type:`function` Substitutes each (non-overlapping) appearance of a string in another.
:zeek:id:`swap_case`: :zeek:type:`function` Swaps the case of every alphabetic character in a string.
:zeek:id:`to_lower`: :zeek:type:`function` Replaces all uppercase letters in a string with their lowercase counterpart.
:zeek:id:`to_string_literal`: :zeek:type:`function` Replaces non-printable characters in a string with escaped sequences.
:zeek:id:`to_title`: :zeek:type:`function` Converts a string to Title Case.
:zeek:id:`to_upper`: :zeek:type:`function` Replaces all lowercase letters in a string with their uppercase counterpart.
:zeek:id:`zfill`: :zeek:type:`function` Returns a copy of a string filled on the left side with zeroes.
====================================================== ==========================================================================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
Functions
#########
.. zeek:id:: clean
:source-code: base/bif/strings.bif.zeek 281 281
:Type: :zeek:type:`function` (str: :zeek:type:`string`) : :zeek:type:`string`
Replaces non-printable characters in a string with escaped sequences. The
mappings are:
- values not in *[32, 126]* to ``\xXX``
If the string does not yet have a trailing NUL, one is added internally.
In contrast to :zeek:id:`escape_string`, this encoding is *not* fully reversible.`
:param str: The string to escape.
:returns: The escaped string.
.. zeek:see:: to_string_literal escape_string
.. zeek:id:: count_substr
:source-code: base/bif/strings.bif.zeek 528 528
:Type: :zeek:type:`function` (str: :zeek:type:`string`, sub: :zeek:type:`string`) : :zeek:type:`count`
Returns the number of times a substring occurs within a string
:param str: The string to search in.
:param substr: The string to search for.
:returns: The number of times the substring occurred.
.. zeek:id:: edit
:source-code: base/bif/strings.bif.zeek 82 82
:Type: :zeek:type:`function` (arg_s: :zeek:type:`string`, arg_edit_char: :zeek:type:`string`) : :zeek:type:`string`
Returns an edited version of a string that applies a special
"backspace character" (usually ``\x08`` for backspace or ``\x7f`` for DEL).
For example, ``edit("hello there", "e")`` returns ``"llo t"``.
:param arg_s: The string to edit.
:param arg_edit_char: A string of exactly one character that represents the
"backspace character". If it is longer than one character Zeek
generates a run-time error and uses the first character in
the string.
:returns: An edited version of *arg_s* where *arg_edit_char* triggers the
deletion of the last character.
.. zeek:see:: clean
to_string_literal
escape_string
strip
.. zeek:id:: ends_with
:source-code: base/bif/strings.bif.zeek 579 579
:Type: :zeek:type:`function` (str: :zeek:type:`string`, sub: :zeek:type:`string`) : :zeek:type:`bool`
Returns whether a string ends with a substring.
.. zeek:id:: escape_string
:source-code: base/bif/strings.bif.zeek 324 324
:Type: :zeek:type:`function` (s: :zeek:type:`string`) : :zeek:type:`string`
Replaces non-printable characters in a string with escaped sequences. The
mappings are:
- values not in *[32, 126]* to ``\xXX``
- ``\`` to ``\\``
In contrast to :zeek:id:`clean`, this encoding is fully reversible.`
:param str: The string to escape.
:returns: The escaped string.
.. zeek:see:: clean to_string_literal
.. zeek:id:: find_all
:source-code: base/bif/strings.bif.zeek 448 448
:Type: :zeek:type:`function` (str: :zeek:type:`string`, re: :zeek:type:`pattern`, max_str_size: :zeek:type:`int` :zeek:attr:`&default` = ``-1`` :zeek:attr:`&optional`) : :zeek:type:`string_set`
Finds all occurrences of a pattern in a string.
:param str: The string to inspect.
:param re: The pattern to look for in *str*.
:param max_str_size: The maximum string size allowed as input. If set to -1, this will use the
:zeek:see:`max_find_all_string_length` global constant. If set to 0, this
check is disabled. If the length of `str` is greater than this size, an
empty set is returned.
:returns: The set of strings in *str* that match *re*, or the empty set.
.. zeek:see: find_all_ordered find_first find_last strstr
.. zeek:id:: find_all_ordered
:source-code: base/bif/strings.bif.zeek 467 467
:Type: :zeek:type:`function` (str: :zeek:type:`string`, re: :zeek:type:`pattern`, max_str_size: :zeek:type:`int` :zeek:attr:`&default` = ``-1`` :zeek:attr:`&optional`) : :zeek:type:`string_vec`
Finds all occurrences of a pattern in a string. The order in which
occurrences are found is preserved and the return value may contain
duplicate elements.
:param str: The string to inspect.
:param re: The pattern to look for in *str*.
:param max_str_size: The maximum string size allowed as input. If set to -1, this will use the
:zeek:see:`max_find_all_string_length` global constant. If set to 0, this
check is disabled. If the length of `str` is greater than this size, an
empty set is returned.
:returns: All strings in *str* that match *re*, or an empty vector.
.. zeek:see: find_all find_first find_last strstr
.. zeek:id:: find_first
:source-code: base/bif/strings.bif.zeek 494 494
:Type: :zeek:type:`function` (str: :zeek:type:`string`, re: :zeek:type:`pattern`) : :zeek:type:`string`
Finds the first occurrence of a pattern in a string.
:param str: The string to inspect.
:param re: The pattern to look for in *str*.
:returns: The first string in *str* that matches *re*, or the empty string.
.. zeek:see:: find_all find_all_ordered find_last strstr
.. zeek:id:: find_last
:source-code: base/bif/strings.bif.zeek 482 482
:Type: :zeek:type:`function` (str: :zeek:type:`string`, re: :zeek:type:`pattern`) : :zeek:type:`string`
Finds the last occurrence of a pattern in a string. This function returns
the match that starts at the largest index in the string, which is not
necessarily the longest match. For example, a pattern of ``/.*/`` will
return the final character in the string.
:param str: The string to inspect.
:param re: The pattern to look for in *str*.
:returns: The last string in *str* that matches *re*, or the empty string.
.. zeek:see: find_all find_all_ordered strstr find_first
.. zeek:id:: find_str
:source-code: base/bif/strings.bif.zeek 551 551
:Type: :zeek:type:`function` (str: :zeek:type:`string`, sub: :zeek:type:`string`, start: :zeek:type:`count` :zeek:attr:`&default` = ``0`` :zeek:attr:`&optional`, end: :zeek:type:`int` :zeek:attr:`&default` = ``-1`` :zeek:attr:`&optional`, case_sensitive: :zeek:type:`bool` :zeek:attr:`&default` = ``T`` :zeek:attr:`&optional`) : :zeek:type:`int`
Finds a string within another string, starting from the beginning. This works
by taking a substring within the provided indexes and searching for the sub
argument. This means that ranges shorter than the string in the sub argument
will always return a failure.
:param str: The string to search in.
:param substr: The string to search for.
:param start: An optional position for the start of the substring.
:param end: An optional position for the end of the substring. A value less than
zero (such as the default -1) means a search until the end of the
string.
:param case_sensitive: Set to false to perform a case-insensitive search.
(default: T). Note that case-insensitive searches use the
``tolower`` libc function, which is locale-sensitive.
:returns: The position of the substring. Returns -1 if the string wasn't
found. Prints an error if the starting position is after the ending
position.
.. zeek:id:: gsub
:source-code: base/bif/strings.bif.zeek 201 201
:Type: :zeek:type:`function` (str: :zeek:type:`string`, re: :zeek:type:`pattern`, repl: :zeek:type:`string`) : :zeek:type:`string`
Substitutes a given replacement string for all occurrences of a pattern
in a given string.
:param str: The string to perform the substitution in.
:param re: The pattern being replaced with *repl*.
:param repl: The string that replaces *re*.
:returns: A copy of *str* with all occurrences of *re* replaced with *repl*.
.. zeek:see:: sub subst_string
.. zeek:id:: hexdump
:source-code: base/bif/strings.bif.zeek 509 509
:Type: :zeek:type:`function` (data_str: :zeek:type:`string`) : :zeek:type:`string`
Returns a hex dump for given input data. The hex dump renders 16 bytes per
line, with hex on the left and ASCII (where printable)
on the right.
:param data_str: The string to dump in hex format.
:returns: The hex dump of the given string.
.. zeek:see:: string_to_ascii_hex bytestring_to_hexstr
.. note:: Based on Netdude's hex editor code.
.. zeek:id:: is_alnum
:source-code: base/bif/strings.bif.zeek 597 597
:Type: :zeek:type:`function` (str: :zeek:type:`string`) : :zeek:type:`bool`
Returns whether a string consists entirely of alphanumeric characters.
The empty string is not alphanumeric.
.. zeek:id:: is_alpha
:source-code: base/bif/strings.bif.zeek 591 591
:Type: :zeek:type:`function` (str: :zeek:type:`string`) : :zeek:type:`bool`
Returns whether a string consists entirely of alphabetic characters.
The empty string is not alphabetic.
.. zeek:id:: is_ascii
:source-code: base/bif/strings.bif.zeek 308 308
:Type: :zeek:type:`function` (str: :zeek:type:`string`) : :zeek:type:`bool`
Determines whether a given string contains only ASCII characters.
The empty string is ASCII.
:param str: The string to examine.
:returns: False if any byte value of *str* is greater than 127, and true
otherwise.
.. zeek:see:: to_upper to_lower
.. zeek:id:: is_num
:source-code: base/bif/strings.bif.zeek 585 585
:Type: :zeek:type:`function` (str: :zeek:type:`string`) : :zeek:type:`bool`
Returns whether a string consists entirely of digits.
The empty string is not numeric.
.. zeek:id:: join_string_set
:source-code: base/bif/strings.bif.zeek 61 61
:Type: :zeek:type:`function` (ss: :zeek:type:`string_set`, sep: :zeek:type:`string`) : :zeek:type:`string`
Joins all values in the given set of strings with a separator placed
between each element.
:param ss: The :zeek:type:`string_set` (``set[string]``).
:param sep: The separator to place between each element.
:returns: The concatenation of all elements in *s*, with *sep* placed
between each element.
.. zeek:see:: cat cat_sep string_cat
fmt
join_string_vec
.. zeek:id:: join_string_vec
:source-code: base/bif/strings.bif.zeek 45 45
:Type: :zeek:type:`function` (vec: :zeek:type:`string_vec`, sep: :zeek:type:`string`) : :zeek:type:`string`
Joins all values in the given vector of strings with a separator placed
between each element.
:param sep: The separator to place between each element.
:param vec: The :zeek:type:`string_vec` (``vector of string``).
:returns: The concatenation of all elements in *vec*, with *sep* placed
between each element.
.. zeek:see:: cat cat_sep string_cat
fmt
.. zeek:id:: levenshtein_distance
:source-code: base/bif/strings.bif.zeek 19 19
:Type: :zeek:type:`function` (s1: :zeek:type:`string`, s2: :zeek:type:`string`) : :zeek:type:`count`
Calculates the Levenshtein distance between the two strings. See `Wikipedia
<http://en.wikipedia.org/wiki/Levenshtein_distance>`__ for more information.
:param s1: The first string.
:param s2: The second string.
:returns: The Levenshtein distance of two strings as a count.
.. zeek:id:: ljust
:source-code: base/bif/strings.bif.zeek 613 613
:Type: :zeek:type:`function` (str: :zeek:type:`string`, width: :zeek:type:`count`, fill: :zeek:type:`string` :zeek:attr:`&default` = ``" "`` :zeek:attr:`&optional`) : :zeek:type:`string`
Returns a left-justified version of the string, padded to a specific length
with a specified character.
:param str: The string to left-justify.
:param count: The length of the returned string. If this value is less than or
equal to the length of str, a copy of str is returned.
:param fill: The character used to fill in any extra characters in the resulting
string. If a string longer than one character is passed, an error is
reported. This defaults to the space character.
:returns: A left-justified version of a string, padded with characters to a
specific length.
.. zeek:id:: lstrip
:source-code: base/bif/strings.bif.zeek 386 386
:Type: :zeek:type:`function` (str: :zeek:type:`string`, chars: :zeek:type:`string` :zeek:attr:`&default` = ``" \x09\x0a\x0d\x0b\x0c"`` :zeek:attr:`&optional`) : :zeek:type:`string`
Removes all combinations of characters in the *chars* argument
starting at the beginning of the string until first mismatch.
:param str: The string to strip characters from.
:param chars: A string consisting of the characters to be removed.
Defaults to all whitespace characters.
:returns: A copy of *str* with the characters in *chars* removed from
the beginning.
.. zeek:see:: sub gsub strip rstrip
.. zeek:id:: remove_prefix
:source-code: base/bif/strings.bif.zeek 658 658
:Type: :zeek:type:`function` (str: :zeek:type:`string`, sub: :zeek:type:`string`) : :zeek:type:`string`
Similar to lstrip(), except does the removal repeatedly if the pattern repeats at the start of the string.
.. zeek:id:: remove_suffix
:source-code: base/bif/strings.bif.zeek 662 662
:Type: :zeek:type:`function` (str: :zeek:type:`string`, sub: :zeek:type:`string`) : :zeek:type:`string`
Similar to rstrip(), except does the removal repeatedly if the pattern repeats at the end of the string.
.. zeek:id:: reverse
:source-code: base/bif/strings.bif.zeek 518 518
:Type: :zeek:type:`function` (str: :zeek:type:`string`) : :zeek:type:`string`
Returns a reversed copy of the string
:param str: The string to reverse.
:returns: A reversed copy of *str*
.. zeek:id:: rfind_str
:source-code: base/bif/strings.bif.zeek 569 569
:Type: :zeek:type:`function` (str: :zeek:type:`string`, sub: :zeek:type:`string`, start: :zeek:type:`count` :zeek:attr:`&default` = ``0`` :zeek:attr:`&optional`, end: :zeek:type:`int` :zeek:attr:`&default` = ``-1`` :zeek:attr:`&optional`, case_sensitive: :zeek:type:`bool` :zeek:attr:`&default` = ``T`` :zeek:attr:`&optional`) : :zeek:type:`int`
The same as :zeek:see:`find_str`, but returns the highest index matching
the substring instead of the smallest.
:param str: The string to search in.
:param substr: The string to search for.
:param start: An optional position for the start of the substring.
:param end: An optional position for the end of the substring. A value less than
zero (such as the default -1) means a search from the end of the string.
:param case_sensitive: Set to false to perform a case-insensitive search.
(default: T). Note that case-insensitive searches use the
``tolower`` libc function, which is locale-sensitive.
:returns: The position of the substring. Returns -1 if the string wasn't
found. Prints an error if the starting position is after the ending
position.
.. zeek:id:: rjust
:source-code: base/bif/strings.bif.zeek 631 631
:Type: :zeek:type:`function` (str: :zeek:type:`string`, width: :zeek:type:`count`, fill: :zeek:type:`string` :zeek:attr:`&default` = ``" "`` :zeek:attr:`&optional`) : :zeek:type:`string`
Returns a right-justified version of the string, padded to a specific length
with a specified character.
:param str: The string to right-justify.
:param count: The length of the returned string. If this value is less than or
equal to the length of str, a copy of str is returned.
:param fill: The character used to fill in any extra characters in the resulting
string. If a string longer than one character is passed, an error is
reported. This defaults to the space character.
:returns: A right-justified version of a string, padded with characters to a
specific length.
.. zeek:id:: rstrip
:source-code: base/bif/strings.bif.zeek 401 401
:Type: :zeek:type:`function` (str: :zeek:type:`string`, chars: :zeek:type:`string` :zeek:attr:`&default` = ``" \x09\x0a\x0d\x0b\x0c"`` :zeek:attr:`&optional`) : :zeek:type:`string`
Removes all combinations of characters in the *chars* argument
starting at the end of the string until first mismatch.
:param str: The string to strip characters from.
:param chars: A string consisting of the characters to be removed.
Defaults to all whitespace characters.
:returns: A copy of *str* with the characters in *chars* removed from
the end.
.. zeek:see:: sub gsub strip lstrip
.. zeek:id:: safe_shell_quote
:source-code: base/bif/strings.bif.zeek 429 429
:Type: :zeek:type:`function` (source: :zeek:type:`string`) : :zeek:type:`string`
Takes a string and escapes characters that would allow execution of
commands at the shell level. Must be used before including strings in
:zeek:id:`system` or similar calls.
:param source: The string to escape.
:returns: A shell-escaped version of *source*. Specifically, this
backslash-escapes characters whose literal value is not otherwise
preserved by enclosure in double-quotes (dollar-sign, backquote,
backslash, and double-quote itself), and then encloses that
backslash-escaped string in double-quotes to ultimately preserve
the literal value of all input characters.
.. zeek:see:: system safe_shell_quote
.. zeek:id:: split_string
:source-code: base/bif/strings.bif.zeek 111 111
:Type: :zeek:type:`function` (str: :zeek:type:`string`, re: :zeek:type:`pattern`) : :zeek:type:`string_vec`
Splits a string into an array of strings according to a pattern.
:param str: The string to split.
:param re: The pattern describing the element separator in *str*.
:returns: An array of strings where each element corresponds to a substring
in *str* separated by *re*.
.. zeek:see:: split_string1 split_string_all split_string_n
.. zeek:id:: split_string1
:source-code: base/bif/strings.bif.zeek 129 129
:Type: :zeek:type:`function` (str: :zeek:type:`string`, re: :zeek:type:`pattern`) : :zeek:type:`string_vec`
Splits a string *once* into a two-element array of strings according to a
pattern. This function is the same as :zeek:id:`split_string`, but *str* is
only split once (if possible) at the earliest position and an array of two
strings is returned.
:param str: The string to split.
:param re: The pattern describing the separator to split *str* in two pieces.
:returns: An array of strings with two elements in which the first represents
the substring in *str* up to the first occurrence of *re*, and the
second everything after *re*. An array of one string is returned
when *s* cannot be split.
.. zeek:see:: split_string split_string_all split_string_n
.. zeek:id:: split_string_all
:source-code: base/bif/strings.bif.zeek 147 147
:Type: :zeek:type:`function` (str: :zeek:type:`string`, re: :zeek:type:`pattern`) : :zeek:type:`string_vec`
Splits a string into an array of strings according to a pattern. This
function is the same as :zeek:id:`split_string`, except that the separators
are returned as well. For example, ``split_string_all("a-b--cd", /(\-)+/)``
returns ``{"a", "-", "b", "--", "cd"}``: odd-indexed elements do match the
pattern and even-indexed ones do not.
:param str: The string to split.
:param re: The pattern describing the element separator in *str*.
:returns: An array of strings where each two successive elements correspond
to a substring in *str* of the part not matching *re* (even-indexed)
and the part that matches *re* (odd-indexed).
.. zeek:see:: split_string split_string1 split_string_n
.. zeek:id:: split_string_n
:source-code: base/bif/strings.bif.zeek 170 170
:Type: :zeek:type:`function` (str: :zeek:type:`string`, re: :zeek:type:`pattern`, incl_sep: :zeek:type:`bool`, max_num_sep: :zeek:type:`count`) : :zeek:type:`string_vec`
Splits a string a given number of times into an array of strings according
to a pattern. This function is similar to :zeek:id:`split_string1` and
:zeek:id:`split_string_all`, but with customizable behavior with respect to
including separators in the result and the number of times to split.
:param str: The string to split.
:param re: The pattern describing the element separator in *str*.
:param incl_sep: A flag indicating whether to include the separator matches in the
result (as in :zeek:id:`split_string_all`).
:param max_num_sep: The number of times to split *str*.
:returns: An array of strings where, if *incl_sep* is true, each two
successive elements correspond to a substring in *str* of the part
not matching *re* (even-indexed) and the part that matches *re*
(odd-indexed).
.. zeek:see:: split_string split_string1 split_string_all
.. zeek:id:: starts_with
:source-code: base/bif/strings.bif.zeek 574 574
:Type: :zeek:type:`function` (str: :zeek:type:`string`, sub: :zeek:type:`string`) : :zeek:type:`bool`
Returns whether a string starts with a substring.
.. zeek:id:: str_smith_waterman
:source-code: base/bif/strings.bif.zeek 346 346
:Type: :zeek:type:`function` (s1: :zeek:type:`string`, s2: :zeek:type:`string`, params: :zeek:type:`sw_params`) : :zeek:type:`sw_substring_vec`
Uses the Smith-Waterman algorithm to find similar/overlapping substrings.
See `Wikipedia <http://en.wikipedia.org/wiki/Smith%E2%80%93Waterman_algorithm>`__.
:param s1: The first string.
:param s2: The second string.
:param params: Parameters for the Smith-Waterman algorithm.
:returns: The result of the Smith-Waterman algorithm calculation.
.. zeek:id:: str_split_indices
:source-code: base/bif/strings.bif.zeek 359 359
:Type: :zeek:type:`function` (s: :zeek:type:`string`, idx: :zeek:type:`index_vec`) : :zeek:type:`string_vec`
Splits a string into substrings with the help of an index vector of cutting
points.
:param s: The string to split.
:param idx: The index vector (``vector of count``) with the cutting points
:returns: A zero-indexed vector of strings.
.. zeek:see:: split_string split_string1 split_string_all split_string_n
.. zeek:id:: strcmp
:source-code: base/bif/strings.bif.zeek 213 213
:Type: :zeek:type:`function` (s1: :zeek:type:`string`, s2: :zeek:type:`string`) : :zeek:type:`int`
Lexicographically compares two strings.
:param s1: The first string.
:param s2: The second string.
:returns: An integer greater than, equal to, or less than 0 according as
*s1* is greater than, equal to, or less than *s2*.
.. zeek:id:: string_cat
:source-code: base/bif/strings.bif.zeek 30 30
:Type: :zeek:type:`function` (...) : :zeek:type:`string`
Concatenates all arguments into a single string. The function takes a
variable number of arguments of type string and stitches them together.
:returns: The concatenation of all (string) arguments.
.. zeek:see:: cat cat_sep
fmt
join_string_vec
.. zeek:id:: string_fill
:source-code: base/bif/strings.bif.zeek 412 412
:Type: :zeek:type:`function` (len: :zeek:type:`int`, source: :zeek:type:`string`) : :zeek:type:`string`
Generates a string of a given size and fills it with repetitions of a source
string.
:param len: The length of the output string.
:param source: The string to concatenate repeatedly until *len* has been reached.
:returns: A string of length *len* filled with *source*.
.. zeek:id:: string_to_ascii_hex
:source-code: base/bif/strings.bif.zeek 333 333
:Type: :zeek:type:`function` (s: :zeek:type:`string`) : :zeek:type:`string`
Returns an ASCII hexadecimal representation of a string.
:param s: The string to convert to hex.
:returns: A copy of *s* where each byte is replaced with the corresponding
hex nibble.
.. zeek:id:: strip
:source-code: base/bif/strings.bif.zeek 369 369
:Type: :zeek:type:`function` (str: :zeek:type:`string`) : :zeek:type:`string`
Strips whitespace at both ends of a string.
:param str: The string to strip the whitespace from.
:returns: A copy of *str* with leading and trailing whitespace removed.
.. zeek:see:: sub gsub lstrip rstrip
.. zeek:id:: strstr
:source-code: base/bif/strings.bif.zeek 226 226
:Type: :zeek:type:`function` (big: :zeek:type:`string`, little: :zeek:type:`string`) : :zeek:type:`count`
Locates the first occurrence of one string in another.
:param big: The string to look in.
:param little: The (smaller) string to find inside *big*.
:returns: The location of *little* in *big*, or 0 if *little* is not found in
*big*.
.. zeek:see:: find_all find_first find_last
.. zeek:id:: sub
:source-code: base/bif/strings.bif.zeek 186 186
:Type: :zeek:type:`function` (str: :zeek:type:`string`, re: :zeek:type:`pattern`, repl: :zeek:type:`string`) : :zeek:type:`string`
Substitutes a given replacement string for the first occurrence of a pattern
in a given string.
:param str: The string to perform the substitution in.
:param re: The pattern being replaced with *repl*.
:param repl: The string that replaces *re*.
:returns: A copy of *str* with the first occurrence of *re* replaced with
*repl*.
.. zeek:see:: gsub subst_string
.. zeek:id:: sub_bytes
:source-code: base/bif/strings.bif.zeek 95 95
:Type: :zeek:type:`function` (s: :zeek:type:`string`, start: :zeek:type:`count`, n: :zeek:type:`int`) : :zeek:type:`string`
Get a substring from a string, given a starting position and length.
:param s: The string to obtain a substring from.
:param start: The starting position of the substring in *s*, where 1 is the first
character. As a special case, 0 also represents the first character.
:param n: The number of characters to extract, beginning at *start*.
:returns: A substring of *s* of length *n* from position *start*.
.. zeek:id:: subst_string
:source-code: base/bif/strings.bif.zeek 240 240
:Type: :zeek:type:`function` (s: :zeek:type:`string`, from: :zeek:type:`string`, to: :zeek:type:`string`) : :zeek:type:`string`
Substitutes each (non-overlapping) appearance of a string in another.
:param s: The string in which to perform the substitution.
:param from: The string to look for which is replaced with *to*.
:param to: The string that replaces all occurrences of *from* in *s*.
:returns: A copy of *s* where each occurrence of *from* is replaced with *to*.
.. zeek:see:: sub gsub
.. zeek:id:: swap_case
:source-code: base/bif/strings.bif.zeek 640 640
:Type: :zeek:type:`function` (str: :zeek:type:`string`) : :zeek:type:`string`
Swaps the case of every alphabetic character in a string. For example, the string "aBc" be returned as "AbC".
:param str: The string to swap cases in.
:returns: A copy of the str with the case of each character swapped.
.. zeek:id:: to_lower
:source-code: base/bif/strings.bif.zeek 252 252
:Type: :zeek:type:`function` (str: :zeek:type:`string`) : :zeek:type:`string`
Replaces all uppercase letters in a string with their lowercase counterpart.
:param str: The string to convert to lowercase letters.
:returns: A copy of the given string with the uppercase letters (as indicated
by ``isascii`` and ``isupper``) folded to lowercase
(via ``tolower``).
.. zeek:see:: to_upper is_ascii
.. zeek:id:: to_string_literal
:source-code: base/bif/strings.bif.zeek 296 296
:Type: :zeek:type:`function` (str: :zeek:type:`string`) : :zeek:type:`string`
Replaces non-printable characters in a string with escaped sequences. The
mappings are:
- values not in *[32, 126]* to ``\xXX``
- ``\`` to ``\\``
- ``'`` and ``""`` to ``\'`` and ``\"``, respectively.
:param str: The string to escape.
:returns: The escaped string.
.. zeek:see:: clean escape_string
.. zeek:id:: to_title
:source-code: base/bif/strings.bif.zeek 650 650
:Type: :zeek:type:`function` (str: :zeek:type:`string`) : :zeek:type:`string`
Converts a string to Title Case. This changes the first character of each sequence of non-space characters
in the string to be capitalized. See https://docs.python.org/3/library/stdtypes.html#str.title for more info.
:param str: The string to convert.
:returns: A title-cased version of the string.
.. zeek:id:: to_upper
:source-code: base/bif/strings.bif.zeek 264 264
:Type: :zeek:type:`function` (str: :zeek:type:`string`) : :zeek:type:`string`
Replaces all lowercase letters in a string with their uppercase counterpart.
:param str: The string to convert to uppercase letters.
:returns: A copy of the given string with the lowercase letters (as indicated
by ``isascii`` and ``islower``) folded to uppercase
(via ``toupper``).
.. zeek:see:: to_lower is_ascii
.. zeek:id:: zfill
:source-code: base/bif/strings.bif.zeek 654 654
:Type: :zeek:type:`function` (str: :zeek:type:`string`, width: :zeek:type:`count`) : :zeek:type:`string`
Returns a copy of a string filled on the left side with zeroes. This is effectively rjust(str, width, "0").
Reference in a new issue View git blame Copy permalink