Skip to content

Commit 01072dc

Browse files
microbit-robertmicrobit-robert
committed
Add docs for referenced string methods
1 parent 20d53ad commit 01072dc

File tree

1 file changed

+161
-18
lines changed

1 file changed

+161
-18
lines changed

‎lang/en/typeshed/stdlib/builtins.pyi

Lines changed: 161 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -360,7 +360,7 @@ class str(Sequence[str]):
360360
def __new__(cls: Type[_T], object: object = "") -> _T:
361361
"""Get a string version of an object.
362362
363-
Example: ``print("The number " + str(42) " is great!")``
363+
Example: ``string = str(42)``
364364
365365
:param object: (default="") Object to return a string version of.
366366
:return: A string reprentation of an object.
@@ -372,7 +372,7 @@ class str(Sequence[str]):
372372
) -> _T:
373373
"""Get a string version of an object.
374374
375-
Example: ``print("The number " + str(42) " is great!")``
375+
Example: ``string = str(42)``
376376
377377
:param object: (default=b"") Object to return a string version of as bytes or a bytearray.
378378
:param encoding: (default="uft-8") Encoding used to decode object.
@@ -385,42 +385,150 @@ class str(Sequence[str]):
385385
x: str,
386386
__start: SupportsIndex | None = ...,
387387
__end: SupportsIndex | None = ...,
388-
) -> int: ...
388+
) -> int:
389+
"""Get the number of non-overlapping occurences of a substring in the string.
390+
391+
The optional ``__start`` and ``__end`` arguments can be used to specify a substring in which to count.
392+
393+
Example: ``count = "banana".count("na")``
394+
395+
:param x: The substring to count.
396+
:param __start: Optional argument to specify the start of the substring in which to count.
397+
:param __end: Optional argument to specify the end of the substring in which to count.
398+
:return: The number of non-overlapping occurences of a substring in the string as an ``int``.
399+
"""
400+
...
389401
def encode(self, encoding: str = ..., errors: str = ...) -> bytes: ...
390402
def endswith(
391403
self,
392404
__suffix: str | Tuple[str, ...],
393405
__start: SupportsIndex | None = ...,
394406
__end: SupportsIndex | None = ...,
395-
) -> bool: ...
407+
) -> bool:
408+
"""Check if the string ends with a substring.
409+
410+
The optional ``__start`` and ``__end`` arguments can be used to specify the range to test.
411+
412+
Example: ``ends_with_hello = "hello, world".endswith("hello")``
413+
414+
:param __prefix: The prefix to check for.
415+
:param __start: Optional argument to specify the start of the substring to test.
416+
:param __end: Optional argument to specify the end of the substring to test.
417+
:return: ``True`` if the string ends with the substring, otherwise ``False``.
418+
"""
419+
...
396420
def find(
397421
self,
398422
__sub: str,
399423
__start: SupportsIndex | None = ...,
400424
__end: SupportsIndex | None = ...,
401-
) -> int: ...
425+
) -> int:
426+
"""Get the lowest index of where the substring is found.
427+
428+
The optional ``__start`` and ``__end`` arguments can be used to specify a substring in which to search.
429+
430+
Example: ``index = "banana".find("na")``
431+
432+
:param __sub: The substring to find.
433+
:param __start: Optional argument to specify the start of the substring in which to search.
434+
:param __end: Optional argument to specify the end of the substring in which to search.
435+
:return: The the lowest index of where the substring is found, -1 if not found.
436+
"""
437+
...
402438
def format(self, *args: object, **kwargs: object) -> str: ...
403439
def index(
404440
self,
405441
__sub: str,
406442
__start: SupportsIndex | None = ...,
407443
__end: SupportsIndex | None = ...,
408444
) -> int: ...
409-
def isalpha(self) -> bool: ...
410-
def isdigit(self) -> bool: ...
411-
def islower(self) -> bool: ...
412-
def isspace(self) -> bool: ...
413-
def isupper(self) -> bool: ...
445+
def isalpha(self) -> bool:
446+
"""Check if all the characters in the string are alphabetical.
447+
448+
Example: ``"Hello".isalpha()``
449+
450+
:return: ``True`` if the string is at least one character long and all the characters in the string are alphabetical, otherwise ``False``.
451+
"""
452+
...
453+
def isdigit(self) -> bool:
454+
"""Check if all the characters in the string are digits.
455+
456+
Example: ``"123".isdigit()``
457+
458+
:return: ``True`` if the string is at least one character long and all the characters in the string are digits, otherwise ``False``.
459+
"""
460+
...
461+
def islower(self) -> bool:
462+
"""Check if all the characters in the string are lower case.
463+
464+
Example: ``"hello".islower()``
465+
466+
:return: ``True`` if the string is at least one character long and all the characters in the string are lower case, otherwise ``False``.
467+
"""
468+
...
469+
def isspace(self) -> bool:
470+
"""Check if all the characters in the string are whitespace characters.
471+
472+
Example: ``" ".isspace()``
473+
474+
:return: ``True`` if the string is at least one character long and all the characters in the string are whitespace characters, otherwise ``False``.
475+
"""
476+
...
477+
def isupper(self) -> bool:
478+
"""Check if all the characters in the string are upper case.
479+
480+
Example: ``"HELLO".isupper()``
481+
482+
:return: ``True`` if the string is at least one character long and all the characters in the string are upper case, otherwise ``False``.
483+
"""
484+
...
414485
def join(self, __iterable: Iterable[str]) -> str: ...
415-
def lower(self) -> str: ...
416-
def lstrip(self, __chars: str | None = ...) -> str: ...
417-
def replace(self, __old: str, __new: str, __count: SupportsIndex = ...) -> str: ...
486+
def lower(self) -> str:
487+
"""Get a copy of the string in lower case.
488+
489+
Example: ``as_lower_case = "HELLO".lower()``
490+
491+
:return: A copy of the string in lower case.
492+
"""
493+
...
494+
def lstrip(self, __chars: str | None = ...) -> str:
495+
"""Get a copy of the string with the leading characters removed.
496+
497+
Example: ``stripped = " hello".lstrip()``
498+
499+
:param __chars: (default=" ") The characters to be removed. Defaults to whitespace characters if not provided.
500+
:return: A copy of the string with the leading characters removed.
501+
"""
502+
...
503+
def replace(self, __old: str, __new: str, __count: SupportsIndex = ...) -> str:
504+
"""Get a copy of the string with all occurrences of the old substring replaced by new.
505+
506+
Example: ``replaced = "apple, orange".replace("orange", "banana")``
507+
508+
:param __old: The substring to replace.
509+
:param __new: The replacement substring.
510+
:param __count: Optional argument to specify the number of occurences of the old substring that should be replaced.
511+
:return: A copy of the string with all occurrences of the old substring replaced by new.
512+
"""
513+
...
418514
def rfind(
419515
self,
420516
__sub: str,
421517
__start: SupportsIndex | None = ...,
422518
__end: SupportsIndex | None = ...,
423-
) -> int: ...
519+
) -> int:
520+
"""Get the highest index of where the substring is found.
521+
522+
The optional ``__start`` and ``__end`` arguments can be used to specify a substring in which to search.
523+
524+
Example: ``index = "banana".rfind("na")``
525+
526+
:param __sub: The substring to find.
527+
:param __start: Optional argument to specify the start of the substring in which to search.
528+
:param __end: Optional argument to specify the end of the substring in which to search.
529+
:return: The the highest index of where the substring is found, -1 if not found.
530+
"""
531+
...
424532
def rindex(
425533
self,
426534
__sub: str,
@@ -430,7 +538,15 @@ class str(Sequence[str]):
430538
def rsplit(
431539
self, sep: str | None = ..., maxsplit: SupportsIndex = ...
432540
) -> list[str]: ...
433-
def rstrip(self, __chars: str | None = ...) -> str: ...
541+
def rstrip(self, __chars: str | None = ...) -> str:
542+
"""Get a copy of the string with the trailing characters removed.
543+
544+
Example: ``stripped = "hello ".rstrip()``
545+
546+
:param __chars: (default=" ") The characters to be removed. Defaults to whitespace characters if not provided.
547+
:return: A copy of the string with the trailing characters removed.
548+
"""
549+
...
434550
def split(
435551
self, sep: str | None = ..., maxsplit: SupportsIndex = ...
436552
) -> list[str]: ...
@@ -439,9 +555,36 @@ class str(Sequence[str]):
439555
__prefix: str | Tuple[str, ...],
440556
__start: SupportsIndex | None = ...,
441557
__end: SupportsIndex | None = ...,
442-
) -> bool: ...
443-
def strip(self, __chars: str | None = ...) -> str: ...
444-
def upper(self) -> str: ...
558+
) -> bool:
559+
"""Check if the string starts with a substring.
560+
561+
The optional ``__start`` and ``__end`` arguments can be used to specify the range to test.
562+
563+
Example: ``starts_with_hello = "hello, world".startswith("hello")``
564+
565+
:param __prefix: The prefix to check for.
566+
:param __start: Optional argument to specify the start of the substring to test.
567+
:param __end: Optional argument to specify the end of the substring to test.
568+
:return: ``True`` if the string starts with the substring, otherwise ``False``.
569+
"""
570+
...
571+
def strip(self, __chars: str | None = ...) -> str:
572+
"""Get a copy of the string with the leading and trailing characters removed.
573+
574+
Example: ``stripped = " hello ".strip()``
575+
576+
:param __chars: (default=" ") The characters to be removed. Defaults to whitespace characters if not provided.
577+
:return: A copy of the string with the leading and trailing characters removed.
578+
"""
579+
...
580+
def upper(self) -> str:
581+
"""Get a copy of the string in upper case.
582+
583+
Example: ``as_upper_case = "hello".upper()``
584+
585+
:return: A copy of the string in upper case.
586+
"""
587+
...
445588
def __add__(self, s: str) -> str: ...
446589
# Incompatible with Sequence.__contains__
447590
def __contains__(self, o: str) -> bool: ... # type: ignore

0 commit comments

Comments
 (0)