Ruby  3.4.0dev (2024-12-06 revision 892c46283a5ea4179500d951c9d4866c0051f27b)
Functions
pathname.h File Reference

(892c46283a5ea4179500d951c9d4866c0051f27b)

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"
Include dependency graph for pathname.h:
This graph shows which files directly or indirectly include this file:

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. More...
 
char * rb_enc_path_skip_prefix (const char *path, const char *end, rb_encoding *enc)
 Seeks for non-prefix part of a pathname. More...
 
char * rb_enc_path_last_separator (const char *path, const char *end, rb_encoding *enc)
 Returns the last path component. More...
 
char * rb_enc_path_end (const char *path, const char *end, rb_encoding *enc)
 This just returns the passed end basically. More...
 
const char * ruby_enc_find_basename (const char *name, long *baselen, long *alllen, rb_encoding *enc)
 Our own encoding-aware version of basename(3). More...
 
const char * ruby_enc_find_extname (const char *name, long *len, rb_encoding *enc)
 Our own encoding-aware version of extname. More...
 

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
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]pathWhere to start scanning.
[in]endEnd of the path string.
[in]encEncoding 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 3594 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]pathWhere to start scanning.
[in]endEnd of the path string.
[in]encEncoding 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 3560 of file file.c.

Referenced by ruby_init_loadpath().

◆ 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]pathWhere to start scanning.
[in]endEnd of the path string.
[in]encEncoding 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 3512 of file file.c.

Referenced by rb_enc_path_skip_prefix().

◆ 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]pathWhere to start scanning.
[in]endEnd of the path string.
[in]encEncoding 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 3526 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]nameTarget path.
[out]baselenReturn buffer.
[in,out]alllenNumber 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 4735 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);
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.
}
rb_encoding * rb_ascii8bit_encoding(void)
Queries the encoding that represents ASCII-8BIT a.k.a.
Definition: encoding.c:1463
int len
Length of the buffer.
Definition: io.h:8
const char * ruby_enc_find_extname(const char *name, long *len, rb_encoding *enc)
Our own encoding-aware version of extname.
Definition: file.c:4982
Parameters
[in]nameTarget path.
[in,out]lenNumber of bytes of name.
[in]encEncoding of name.
Returns
See above.
Postcondition
len, if passed, is updated (see above).

Definition at line 4982 of file file.c.