Ruby: include/ruby/internal/encoding/pathname.h File Reference

Ruby 3.3.4p94 (2024-07-09 revision be1089c8ec5ba40e09b1553e36b3174bf4014d9d)

Functions
pathname.h File Reference

Routines to manipulate encodings of pathnames. More...

`#include "ruby/internal/attr/nonnull.h"`
`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/encoding/encoding.h"`
`#include "ruby/internal/value.h"`

Go to the source code of this file.

## Functions
char * | rb_enc_path_next (const char *path, const char *end, rb_encoding *enc)
| Returns a path component directly adjacent to the passed pointer.
char * | rb_enc_path_skip_prefix (const char *path, const char *end, rb_encoding *enc)
| Seeks for non-prefix part of a pathname.
char * | rb_enc_path_last_separator (const char *path, const char *end, rb_encoding *enc)
| Returns the last path component.
char * | rb_enc_path_end (const char *path, const char *end, rb_encoding *enc)
| This just returns the passed end basically.
const char * | ruby_enc_find_basename (const char *name, long *baselen, long *alllen, rb_encoding *enc)
| Our own encoding-aware version of `basename(3)`.
const char * | ruby_enc_find_extname (const char *name, long *len, rb_encoding *enc)
| Our own encoding-aware version of `extname`.

## Detailed Description

Routines to manipulate encodings of pathnames.

Author
  Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org

Copyright
  This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.

Warning
  Symbols prefixed with either `RBIMPL` or `rbimpl` are implementation details. Don't take them as canon. They could rapidly appear then vanish. The name (path) of this header file is also an implementation detail. Do not expect it to persist at the place it is now. Developers are free to move it anywhere anytime at will.

Note
  To ruby-core: remember that this header can be possibly recursively included from extension libraries written in C++. Do not expect for instance `__VA_ARGS__` is always available. We assume C99 for ruby itself but we don't assume languages of extension libraries. They could be written in C++98.

Definition in file pathname.h.

## Function Documentation

## ◆ rb_enc_path_end()

char * rb_enc_path_end | ( | const char * | path,
|  | const char * | end,
|  | rb_encoding * | enc )

This just returns the passed end basically.

It makes difference in case the passed string ends with tons of path separators like the following:

"/path/that/ends/with/lots/of/slashes//////////////"
^ ^ ^
| | +--- end
| +--- @return
+--- path

Parameters

  [in] | path | Where to start scanning.
  [in] | end | End of the path string.
  [in] | enc | Encoding of the string.

Returns
  A pointer in the passed string where the trailing path separators start, or `end` if there is no trailing path separators.

Definition at line 3500 of file file.c.

## ◆ rb_enc_path_last_separator()

char * rb_enc_path_last_separator | ( | const char * | path,
|  | const char * | end,
|  | rb_encoding * | enc )

Returns the last path component.

"/multi/byte/encoded/pathname.txt"
^ ^ ^
| | +--- end
| +--- @return
+--- path

Parameters

  [in] | path | Where to start scanning.
  [in] | end | End of the path string.
  [in] | enc | Encoding of the string.

Returns
  A pointer in the passed string where the last path component resides, or `end` if there is no more path component.

Definition at line 3466 of file file.c.

## ◆ rb_enc_path_next()

char * rb_enc_path_next | ( | const char * | path,
|  | const char * | end,
|  | rb_encoding * | enc )

Returns a path component directly adjacent to the passed pointer.

"/multi/byte/encoded/pathname.txt"
^ ^ ^
| | +--- end
| +--- @return
+--- path

Parameters

  [in] | path | Where to start scanning.
  [in] | end | End of the path string.
  [in] | enc | Encoding of the string.

Returns
  A pointer in the passed string where the next path component resides, or `end` if there is no next path component.

Definition at line 3418 of file file.c.

## ◆ rb_enc_path_skip_prefix()

char * rb_enc_path_skip_prefix | ( | const char * | path,
|  | const char * | end,
|  | rb_encoding * | enc )

Seeks for non-prefix part of a pathname.

This can be a no-op when the OS has no such concept like a path prefix. But there are OSes where path prefixes do exist.

"C:\multi\byte\encoded\pathname.txt"
^ ^ ^
| | +--- end
| +--- @return
+--- path

Parameters

  [in] | path | Where to start scanning.
  [in] | end | End of the path string.
  [in] | enc | Encoding of the string.

Returns
  A pointer in the passed string where non-prefix part starts, or `path` if the OS does not have path prefix.

Definition at line 3432 of file file.c.

## ◆ ruby_enc_find_basename()

const char * ruby_enc_find_basename | ( | const char * | name,
|  | long * | baselen,
|  | long * | alllen,
|  | rb_encoding * | enc )

Our own encoding-aware version of `basename(3)`.

Normally, this function returns the last path component of the given name. However in case the passed name ends with a path separator, it returns the name of the directory, not the last (empty) component. Also if the passed name is a root directory, it returns that root directory. Note however that Windows filesystem have drive letters, which this function does not return.

Parameters

  [in] | name | Target path.
  [out] | baselen | Return buffer.
  [in,out] | alllen | Number of bytes of `name`.
  | [enc] | enc Encoding of `name`.

Returns
  The rightmost component of `name`.

Postcondition
  `baselen`, if passed, is updated to be the number of bytes of the returned basename.
  `alllen`, if passed, is updated to be the number of bytes of strings not considered as the basename.

Definition at line 4625 of file file.c.

## ◆ ruby_enc_find_extname()

const char * ruby_enc_find_extname | ( | const char * | name,
|  | long * | len,
|  | rb_encoding * | enc )

Our own encoding-aware version of `extname`.

This function first applies rb_enc_path_last_separator() to the passed name and only concerns its return value (ignores any parent directories). This function returns complicated results:

auto path = "...";
auto len = strlen(path);
auto ret = ruby_enc_find_extname(path, &len, rb_ascii8bit_encoding());
switch(len) {
case 0:
if (ret == 0) {
// `path` is a file without extensions.
}
else {
// `path` is a dotfile.
// `ret` is the file's name.
}
break;
case 1:
// `path` _ends_ with a dot.
// `ret` is that dot.
break;
default:
// `path` has an extension.
// `ret` is that extension.
}
len
int len
Length of the buffer.
Definition io.h:8

Parameters

  [in] | name | Target path.
  [in,out] | len | Number of bytes of `name`.
  [in] | enc | Encoding of `name`.

Returns
  See above.

Postcondition
  `len`, if passed, is updated (see above).

Definition at line 4872 of file file.c.